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. An event's payments, billing item totals, line items, and category totals can also be included by adding the parameter '&show_financial=true' .

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
  • setup_time - Time (in minutes) for setup
  • teardown_time - Time (in minutes) for teardown
  • event_start_time_with_setup_time - Start date time including setup time
  • event_end_time_with_teardown_time - End date time including teardown time
  • 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_id - ID of Event Type (See sites API for values)
  • lead_source_id - ID of Lead Source (See sites API for values)
  • lost_reason - ID, NAME of Lost Reason
  • lost_reason_details - Reason entered for Lost event.
  • 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 - Collection of 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.)
  • documents Collection of Event's generated documents, including links to each
  • document_ids - List of Document IDs belong to this event

Event Financial Fields

These are only visible by adding the parameter '&show_financial=true'. This will add the following financial details under the documents node.

  • line_items - Collection of line items listed
    • id - Integer
    • description - String
    • value - Currency
    • total_price Currency
  • billing_totals - Collection of billing totals
    • description String
    • value Currency
    • total_price Currency
  • category_totals Collection
    • name String
    • value Currency
  • payment_set - Record that represents a set of payments for the attached document
    • amount_due Currency
    • running_balance Currency
    • remaining_payment_amount Currency
    • document_name - Name of associated Document (if applicable)
    • payments - Collection - all payments belonging to the payment_set
    • amount Currency
    • state String
    • billing_kind String - type of payment (deposit, amount_due, etc.)
    • custom_title String - optional custom title

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, event_end_date - (iso8601) searches for events starting within the specified date range
  • event_created_start_date, event_created_end_date - (iso8601) searches for events created within the specified date range
  • event_updated_start_date, event_updated_end_date - (iso8601) searches for events updated within the specified date range
  • date_range_startdate_range_end - (iso8601) searches for events overlapping the specified date range
  • room_ids - comma separated list of room ID's to match on
  • location_ids - comma separated list of location ID's to match on 
  • custom_field_values[][custom_field_id] - Custom Field ID (pair with a custom_field_value)
  • custom_field_values[][custom_field_value] - Custom Field Value (pair with a custom_field_id)
  • page (1..9999999)
  • active - when set to true will only return events that have not been deleted

Date parameters may be specified as MM/DD/YYYY or in ISO 8601 format as a date with optional time: YYYY-MM-DDThh:mm:ss.

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