Sign In Try it free

Listing Calendars


An event represents a single entry in a calendar and contains all the usual information such as timing, location, attendance, recurrence etc.

The sort order for events is oldest-first.

Event model

See event model in the reference.

Listing events

When listing events, if no filters are specified then the system will retrieve only events from the primary/default calendar.


          token = "<user's token>"
client =

emails = client.list_events

# => [LivilApi::Event(id: '...', name: 'Meeting with the team', ...), ...]

Applying Filters

There are a number of filters which may be applied to the request in order to limit the returned results.

Unless othewise specified below, all filteirng and seraching is performed by the provider APIs. Contents are not scanned by the WorkAPI system.

Standard Parameters

The event list endpoint supports the following standard parameters:


The calendar_ids filter allows retrieval of events for one or many specified calendars.


events = client.list_events(calendar_ids: ['ABCDE...'])

# => [LivilApi::Event(id: '...', ..., calendar: LivilApi::Calendar(id: 'ABCDE...')), ...]

Date range

The date range filters by the starts_at date and time. Any events that begin between those dates will be included in the result set.


events = client.list_events(date_from: '2019-10-01T00:00z', date_until: '2019-12-31T00:00z') 

# => [LivilApi::Event(id: '...', ..., starts_at: '2019-11-01T10:30z')]

Reurring Event ID

If an event is set to recur, all recurrences are retrieved when filtering by recurring_event_id.

The calendar_ids field should contain a single ID, that of the calendar to which the the recurring event belongs.


events = client.list_events(calendar_ids: ['ABCD987...'], recurring_event_id: 'XYZ123...') 

# => [LivilApi::Event(id: '...', ..., parent_event_id: 'XYZ123...')]

Simple search text

A keyword search is performed on events in the specified calendars (default: all).


 events = client.list_events(search_text: 'your subscription') 

# => [LivilApi::Event(id: '...', description: 'Cancel your subscription with XYZ inc.')]  

First 50,000 requests are free every month