> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # ListEvents # Package: calendar # Namespace: ExternalCalendarService # Method link: https://dev.wix.com/docs/api-reference/business-solutions/bookings/calendar/external-calendar-v2/list-events.md ## Permission Scopes: Manage External Calendars: SCOPE.DC-BOOKINGS.MANAGE-EXTERNAL-CALENDARS ## Introduction Retrieves a list of events from all external calendar accounts, based on the provided filtering and paging. --- ## REST API ### Schema ``` Method: listEvents Description: Retrieves a list of events from all external calendar accounts, based on the provided filtering and paging. ### Filters You must filter by specifying both `from` and `to` dates, unless you specify `cursorPaging.cursor`. Additionally, you can specify `scheduleIds` or `userIds` to further limit which events are returned. By default, events related to all schedules and Wix users are returned. ### Sorting Returned events are sorted by start date in ascending order. You can't adjust the sorting. ### Personal data By default, the following `event` fields aren't returned: + `calendarName`. + `title`. + `scheduleOwnerName`. You can retrieve these fields, by specifying `{"fieldsets": "OWN_PI"}`. ### Partial success By default, the call fails if events for at least 1 connection can't be retrieved from an external provider. However, you can specify `{"partialFailure": true}` to allow the call to succeed, if details for at least 1 connection can be retrieved. URL: https://www.wixapis.com/bookings/v2/external-calendars/events Method: GET Method parameters: query param name: allDay | type: allDay | description: Whether to include only all-day events in the returned list. If `true`, only all-day events are returned. If `false`, only events with a specified time are returned. Default: All events are returned. param name: cursorPaging | type: CursorPaging - name: limit | type: integer | description: Number of events to load. Max: `1000` - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. You can get the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. query param name: fieldsets | type: array | description: Predefined sets of fields to return. - `NO_PI`: Returns event objects without personal information. - `OWN_PI`: Returns complete event objects, including personal information. Default: `NO_PI` query param name: from | type: from | description: Date and time from which to retrieve events, formatted according to [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt). Required, unless `cursorPaging.cursor` is provided. Events which start before the `from` time and end after it are included in the returned list. query param name: partialFailure | type: partialFailure | description: Whether to return a partial list of events if details can't be retrieved for some connections. Default: `false` query param name: scheduleIds | type: array | description: Schedule GUIDs to filter by. If provided, the returned list includes only events belonging to external calendars connected to the specified schedules. Maximum of 100 schedule GUIDs per request. query param name: to | type: to | description: Date and time until which to retrieve events, formatted according to [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt). Required, unless `cursorPaging.cursor` is provided. Events which start before the `to` time and end after it are included in the returned list. query param name: userIds | type: array | description: Wix user GUIDs to filter by. If provided, the returned list includes only events belonging to external calendars connected to schedules belonging to the specified Wix users. Maximum of 100 Wix user GUIDs per request. Return type: ListEventsResponse - name: events | type: array | description: List of external calendar events matching the filters. - name: scheduleId | type: string | description: GUID of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/introduction.md) to which the event belongs. - name: calendarType | type: CalendarType | description: External calendar type. - enum: - UNDEFINED: There is no information about the external calendar type. - GOOGLE: [Google Calendar](https://developers.google.com/calendar/api/guides/overview). - I_CAL: Apple iCalendar. - OUTLOOK: __Deprecated__. Use `MICROSOFT` instead. - OFFICE_365: __Deprecated__. Use `MICROSOFT` instead. - MICROSOFT: Microsoft Calendar. For example, Office 365 calendar or Outlook calendar. - OTHER: A different type of external calendar, not listed here. - name: calendarName | type: string | description: Display name of the external calendar. For example, `Primary` or `Birthdays`. - name: title | type: string | description: Event title. - name: start | type: string | description: Start date and time of the event (inclusive), formatted according to [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt). - name: end | type: string | description: End date and time of the event (exclusive), formatted according to [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt). - name: allDay | type: boolean | description: Whether the event is an all-day event. Default: `false` - name: scheduleOwnerId | type: string | description: GUID of the [Wix user](https://dev.wix.com/docs/rest/articles/getting-started/about-identities.md#wix-user) to whom the schedule belongs. For Bookings [staff members](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/introduction.md) identical to their [resource GUID](https://dev.wix.com/docs/rest/business-solutions/bookings/resources/resources-v2/introduction.md). - name: scheduleOwnerName | type: string | description: Name of the [Wix user](https://dev.wix.com/docs/rest/articles/getting-started/about-identities.md#wix-user) to whom the schedule belongs. For example, the `name` of a Bookings [staff member](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/introduction.md). - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata. - name: count | type: integer | description: Number of items returned in the response. - name: cursors | type: Cursors | description: Offset that was requested. - name: next | type: string | description: Cursor pointing to next page in the list of results. - name: hasNext | type: boolean | description: Indicates if there are more results after the current page. If `true`, another page of results can be retrieved. If `false`, this is the last page. - name: failedProviderIds | type: array | description: List of provider GUIDs for connections for which retrieval of events failed. Returned only if `partialFailure` body parameter is `true` in the request. ``` ### Examples ### List all events within a specified time range ```curl curl -X GET 'https://www.wixapis.com/bookings/v2/external-calendars/events?from=2022-12-31T22:00:00.000Z&to=2023-01-07T21:59:59.999Z' \ -H 'Authorization: ' ``` ### List all events within a specified time range and include personal information ```curl curl -X GET 'https://www.wixapis.com/bookings/v2/external-calendars/events?from=2022-12-31T22:00:00.000Z&to=2023-01-07T21:59:59.999Z&fieldsets=OWN_PI' \ -H 'Authorization: ' ``` ### List the next page of events within a specified time range using a cursor obtained in the previous request ```curl curl -X GET 'https://www.wixapis.com/bookings/v2/external-calendars/events?from=2022-12-31T22:00:00.000Z&to=2023-01-07T21:59:59.999Z&cursorPaging.cursor=JWE.eyJhbGciOiJBMTI4S1ciLCJlbm...' \ -H 'Authorization: ' ``` ### List a limited number of events within a specified time range ```curl curl -X GET 'https://www.wixapis.com/bookings/v2/external-calendars/events?from=2022-12-31T22:00:00.000Z&to=2023-01-07T21:59:59.999Z&cursorPaging.limit=2' \ -H 'Authorization: ' ``` ### List events connected to a specified schedule within a specified time range ```curl curl -X GET 'https://www.wixapis.com/bookings/v2/external-calendars/events?from=2022-12-31T22:00:00.000Z&to=2023-01-07T21:59:59.999Z&scheduleIds=b936298d-18a6-4ae8-8e9f-10bf49314c95' \ -H 'Authorization: ' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.calendar.ExternalCalendarService.listEvents(options) Description: Retrieves a list of events from all external calendar accounts, based on the provided filtering and paging. ### Filters You must filter by specifying both `from` and `to` dates, unless you specify `cursorPaging.cursor`. Additionally, you can specify `scheduleIds` or `userIds` to further limit which events are returned. By default, events related to all schedules and Wix users are returned. ### Sorting Returned events are sorted by start date in ascending order. You can't adjust the sorting. ### Personal data By default, the following `event` fields aren't returned: + `calendarName`. + `title`. + `scheduleOwnerName`. You can retrieve these fields, by specifying `{"fieldsets": "OWN_PI"}`. ### Partial success By default, the call fails if events for at least 1 connection can't be retrieved from an external provider. However, you can specify `{"partialFailure": true}` to allow the call to succeed, if details for at least 1 connection can be retrieved. Method parameters: param name: options | type: ListEventsOptions none - name: from | type: string | description: Date and time from which to retrieve events, formatted according to [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt). Required, unless `cursorPaging.cursor` is provided. Events which start before the `from` time and end after it are included in the returned list. - name: to | type: string | description: Date and time until which to retrieve events, formatted according to [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt). Required, unless `cursorPaging.cursor` is provided. Events which start before the `to` time and end after it are included in the returned list. - name: scheduleIds | type: array | description: Schedule GUIDs to filter by. If provided, the returned list includes only events belonging to external calendars connected to the specified schedules. Maximum of 100 schedule GUIDs per request. - name: userIds | type: array | description: Wix user GUIDs to filter by. If provided, the returned list includes only events belonging to external calendars connected to schedules belonging to the specified Wix users. Maximum of 100 Wix user GUIDs per request. - name: allDay | type: boolean | description: Whether to include only all-day events in the returned list. If `true`, only all-day events are returned. If `false`, only events with a specified time are returned. Default: All events are returned. - name: fieldsets | type: array | description: Predefined sets of fields to return. - `NO_PI`: Returns event objects without personal information. - `OWN_PI`: Returns complete event objects, including personal information. Default: `NO_PI` - name: cursorPaging | type: CursorPaging | description: Pagination options. - name: limit | type: integer | description: Number of events to load. Max: `1000` - name: cursor | type: string | description: Pointer to the next or previous page in the list of results. You can get the relevant cursor token from the `pagingMetadata` object in the previous call's response. Not relevant for the first request. - name: partialFailure | type: boolean | description: Whether to return a partial list of events if details can't be retrieved for some connections. Default: `false` Return type: PROMISE - name: events | type: array | description: List of external calendar events matching the filters. - name: scheduleId | type: string | description: GUID of the [schedule](https://dev.wix.com/docs/rest/business-management/calendar/schedules-v3/introduction.md) to which the event belongs. - name: calendarType | type: CalendarType | description: External calendar type. - enum: - UNDEFINED: There is no information about the external calendar type. - GOOGLE: [Google Calendar](https://developers.google.com/calendar/api/guides/overview). - I_CAL: Apple iCalendar. - OUTLOOK: __Deprecated__. Use `MICROSOFT` instead. - OFFICE_365: __Deprecated__. Use `MICROSOFT` instead. - MICROSOFT: Microsoft Calendar. For example, Office 365 calendar or Outlook calendar. - OTHER: A different type of external calendar, not listed here. - name: calendarName | type: string | description: Display name of the external calendar. For example, `Primary` or `Birthdays`. - name: title | type: string | description: Event title. - name: start | type: string | description: Start date and time of the event (inclusive), formatted according to [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt). - name: end | type: string | description: End date and time of the event (exclusive), formatted according to [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt). - name: allDay | type: boolean | description: Whether the event is an all-day event. Default: `false` - name: scheduleOwnerId | type: string | description: GUID of the [Wix user](https://dev.wix.com/docs/rest/articles/getting-started/about-identities.md#wix-user) to whom the schedule belongs. For Bookings [staff members](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/introduction.md) identical to their [resource GUID](https://dev.wix.com/docs/rest/business-solutions/bookings/resources/resources-v2/introduction.md). - name: scheduleOwnerName | type: string | description: Name of the [Wix user](https://dev.wix.com/docs/rest/articles/getting-started/about-identities.md#wix-user) to whom the schedule belongs. For example, the `name` of a Bookings [staff member](https://dev.wix.com/docs/rest/business-solutions/bookings/staff-members/introduction.md). - name: pagingMetadata | type: CursorPagingMetadata | description: Paging metadata. - name: count | type: integer | description: Number of items returned in the response. - name: cursors | type: Cursors | description: Offset that was requested. - name: next | type: string | description: Cursor pointing to next page in the list of results. - name: hasNext | type: boolean | description: Indicates if there are more results after the current page. If `true`, another page of results can be retrieved. If `false`, this is the last page. - name: failedProviderIds | type: array | description: List of provider GUIDs for connections for which retrieval of events failed. Returned only if `partialFailure` body parameter is `true` in the request. ``` ### Examples ### List events including personal information (with elevated permissions) ```javascript import { externalCalendars } from '@wix/bookings'; import { auth } from '@wix/essentials'; const elevatedListEvents = auth.elevate(externalCalendars.listEvents); async function listEventsWithPI(from, to) { const options = { from, to, fieldsets: ['OWN_PI'] } const {events: eventsWithPI} = await elevatedListEvents(options) return eventsWithPI } ``` ### List events including personal information ```javascript import {externalCalendars} from '@wix/bookings'; async function listEventsWithPI(from, to) { const options = { from, to, fieldsets: ['OWN_PI'] } const {events: eventsWithPI} = await externalCalendars.listEvents(options) return eventsWithPI } ``` ### List events connected to a specified schedule (with elevated permissions) ```javascript import { externalCalendars } from '@wix/bookings'; import { auth } from '@wix/essentials'; const elevatedListEvents = auth.elevate(externalCalendars.listEvents); async function listScheduleEvents(from, to) { const options = { from, to, scheduleId: 'b936298d-18a6-4ae8-8e9f-10bf49314c95' } const { events: eventsOfSchedule } = await elevatedListEvents(options) return eventsOfSchedule } ``` ### List events connected to a specified schedule ```javascript import {externalCalendars} from '@wix/bookings'; async function listScheduleEvents(from, to) { const options = { from, to, scheduleId: 'b936298d-18a6-4ae8-8e9f-10bf49314c95' } const {events: eventsOfSchedule} = await externalCalendars.listEvents(options) return eventsOfSchedule } ``` ### List all events within a time range (with elevated permissions) ```javascript import { externalCalendars } from '@wix/bookings'; import { auth } from '@wix/essentials'; const elevatedListEvents = auth.elevate(externalCalendars.listEvents); async function listEvents() { const options = { from: '2023-01-01T00:00:00Z', to: '2023-01-07T00:00:00Z' } const { events } = await elevatedListEvents(options); return events; } ``` ### List all events within a time range ```javascript import {externalCalendars} from '@wix/bookings'; async function listEvents() { const options = { from: '2023-01-01T00:00:00Z', to: '2023-01-07T00:00:00Z' } const {events} = await externalCalendars.listEvents(options) return events } ``` ### listEvents (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { externalCalendars } from '@wix/bookings'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { externalCalendars }, // Include the auth strategy and host as relevant }); async function listEvents(options) { const response = await myWixClient.externalCalendars.listEvents(options); }; ``` ---