# Events ## Get All Events From a Calendar `GET` `https://api.pyas.io/google/events` #### Query Parameters | Name | Type | Description | | -------------------------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | calendarId\* | String | The id of the Google calendar | | accountId\* | String | The user's Pyas account id. This is returned when you connect an account to Pyas. | | startDate | Timestamp/Date String |

Filter events by start date

(ex: 01-01-2022)

| | endDate | Timestamp/Date String |

Filter events by end time

(ex: 01-01-2023)

| | search | String | Free text search terms to find events that match these terms in the following fields: `summary`, `description`, `location`, attendee's `displayName`, attendee's `email`. | | nextPageToken | String | Token string used to get the next page of results (paginate) | | maxResults | Integer | Max number of results to return per page | | syncToken | String | Token obtained from the `nextSyncToken` field returned on the last page of results | | eventTypes | String |

Event types to return. Acceptable values are:

| | iCalUID | String | Use this if you want to search for an event by its iCalendar ID. | | maxAttendees | Integer | The maximum number of attendees to include in the response. | | orderBy | String |

The order of the events returned in the result. Acceptable values are:

| | privateExtendedProperty | String | Extended properties constraint specified as `propertyName=value`. Matches only private properties. | | sharedExtendedProperty | String | Extended properties constraint specified as `propertyName=value`. Matches only shared properties | | showDeleted | Boolean | Whether to include deleted events (with status = "cancelled") in the result. | | singleEvents | Boolean | Whether to expand recurring events into instances and only return single one-off events and instances of recurring events, but not the underlying recurring events themselves. Optional. The default is False. | | timeZone | String | Time zone used in the response. Optional. The default is the time zone of the calendar. | | showHiddenInvitations | Boolean | Whether to include hidden invitations in the result. Optional. The default is False. | | updatedMin | Timestamp/Date String | Filter events by last modified/updated time | | filters | JSON |

Query filteres provided in JSON key-value pairs.

ex: {"singleEvents": true} Note: This is supported, but not recommended.

See possible filters list below.

| #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API key | {% tabs %} {% tab title="200: OK Successfully retrieved events" %} 
{
    "success": true,
    "data": {
        "nextSyncToken": string|null,
        "nextPageToken": string|null,
        "events": [
            {
                "kind": "calendar#event",
                "etag": "\"00000\"",
                "id": "string",
                "status": "confirmed",
                "htmlLink": "string",
                "created": "2023-01-05T01:56:37.000Z",
                "updated": "2023-01-05T01:56:38.403Z",
                "summary": "some summary",
                "description": "some description",
                "creator": {
                    "email": "string"
                },
                "organizer": {
                    "email": "string"
                },
                "start": {
                    "dateTime": "2023-01-11T13:00:00-05:00",
                    "timeZone": "UTC"
                },
                "end": {
                    "dateTime": "2023-01-11T13:15:00-05:00",
                    "timeZone": "UTC"
                },
                "iCalUID": "string",
                "sequence": 0,
                "attendees": [
                    {
                        "email": "string",
                        "organizer": true,
                        "responseStatus": "string"
                    },
                    {
                        "email": "string",
                        "self": true,
                        "responseStatus": "stringd"
                    }
                ],
                "reminders": {
                    "useDefault": boolean
                },
                "eventType": "string"
            },
        ]
    }
}
{% endtab %} {% tab title="401: Unauthorized Invalid/missing API key" %} ```json { "error": "Unauthorized. Invalid API key." } ``` {% endtab %} {% tab title="400: Bad Request Missing calendar id" %} ```json { "errors": [ { "msg": "a calendar id is required.", "param": "calendarId", "location": "query" } ] } ``` {% endtab %} {% tab title="400: Bad Request Missing account id" %} ```json { "errors": [ { "msg": "an account id is required.", "param": "accountId", "location": "query" } ] } ``` {% endtab %} {% tab title="400: Bad Request Missing both calendar id and account id" %} ```json { "errors": [ { "msg": "an account id is required.", "param": "accountId", "location": "query" }, { "msg": "a calendar id is required.", "param": "calendarId", "location": "query" } ] } ``` {% endtab %} {% tab title="404: Not Found Account Not Found. Invalid accountId" %} ```json { "success": false, "error": "Invalid account id. Account Not Found", "code": 404 } ``` {% endtab %} {% tab title="404: Not Found Calendar Not Found" %} ```json { "success": false, "error": "Not Found", "code": 404 } ``` {% endtab %} {% endtabs %} *** #### List of Possible Filters Below is a list of flags/filters that can be used when listing events. Simply send these as JSON in the `filters` parameter. We support this, but it's better to send these filters as single query parameters. ```typescript startDate, endDate, nextPageToken, search, maxResults, filters, syncToken, eventTypes, iCalUID, maxAttendees, orderBy, privateExtendedProperty, sharedExtendedProperty, showDeleted, showHiddenInvitations, singleEvents, timeZone, updatedMin, ``` ## Get Event by ID `GET` `https://api.pyas.io/google/events/{id}` Gets a calendar event by id #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------ | | {id}\* | String | The event id | #### Query Parameters | Name | Type | Description | | -------------------------------------------- | ------ | --------------------------------------------------------------------------------- | | calendarId\* | String | The Google Calendar id | | accountId\* | String | The user's Pyas account id. This is returned when you connect an account to Pyas. | #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API key | {% tabs %} {% tab title="200: OK Successfully retrieved the event" %} ```json { "success": true, "data": { "event": { "kind": "calendar#event", "etag": "\"00000000\"", "id": "string", "status": "string", "htmlLink": "string", "created": "2023-01-05T01:56:37.000Z", "updated": "2023-01-05T01:56:38.403Z", "summary": "some summary", "description": "some description" "email": "string" }, "organizer": { "email": "string" }, "start": { "dateTime": "2023-01-11T13:00:00-05:00", "timeZone": "UTC" }, "end": { "dateTime": "2023-01-11T13:15:00-05:00", "timeZone": "UTC" }, "iCalUID": "string", "sequence": 0, "attendees": [ { "email": "string", "organizer": true, "responseStatus": "accepted" }, { "email": "string", "self": true, "responseStatus": "accepted" } ], "reminders": { "useDefault": true }, "eventType": "default" } } } ``` {% endtab %} {% tab title="401: Unauthorized Invalid/Missing API key" %} ```json { "error": "Unauthorized. Invalid API key." } ``` {% endtab %} {% tab title="400: Bad Request Missing fields" %} ```json { "errors": [ { "msg": "calendar id is required", "param": "calendarId", "location": "query" }, { "msg": "calendar id must be a string", "param": "calendarId", "location": "query" } ] } ``` {% endtab %} {% tab title="404: Not Found Calendar Not Found" %} ```json { "success": false, "error": "Not Found", "code": 404 } ``` {% endtab %} {% tab title="404: Not Found Account Not Found. Invalid accountId" %} ```json { "success": false, "error": "Invalid account id. Account Not Found", "code": 404 } ``` {% endtab %} {% endtabs %} ## Create Event `POST` `https://api.pyas.io/google/events` Creates a calendar event #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API key | #### Request Body | Name | Type | Description | | ------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------- | | accountId\* | String | The user's Pyas account id. This is returned when you connect an account to Pyas. | | calendarId\* | String | The Google calendar id | | eventData\* | Object | The event data. See the Required [**Event Data Object**](#event-data-object-example) example below. | | eventData.title\* | String | The event title | | eventData.description\* | String | Event description | | eventData.startDate\* | DateTime | RFC3339 Timestamp | | eventData.endDate\* | DateTime | RFC3339 Timestamp | | eventData.timeZone | String | Time Zone in IANA format | | eventData.location | Object | Location object - See the example [**Event Location Object**](#event-location-object-example) | | eventData.attendees | Array | Array of [**Attendee Objects**](#attendee-object-example) | | eventData.conferencing | Object | An [**Event Conferencing Object**](#event-conferencing-object-example) | | eventData.phone | String | Phone number | | eventData.phonePin | String | Optional pin if one is required to join the meeting | | eventData.recurrence | Object | Recurrence object for recurring events. See the [**Recurrence Object**](#recurrence-object) below. | | eventData.meta | Object | Optional. Use this to add additional/extra event body fields. | {% tabs %} {% tab title="200: OK Event created" %} ```json { "success": true, "data": { "kind": "calendar#event", "etag": "\"000000000000000\"", "id": "string", "status": "confirmed", "htmlLink": "string", "created": "2023-03-06T23:06:14.000Z", "updated": "2023-03-06T23:06:14.350Z", "summary": "Example Event", "description": "example", "location": "712 Applesauce Rd Austin, TX 73301", "creator": { "email": "example@gmail.com", "self": true }, "organizer": { "email": "example@gmail.com", "self": true }, "start": { "dateTime": "2023-03-06T18:06:12-05:00", "timeZone": "America/New_York" }, "end": { "dateTime": "2023-03-06T18:36:12-05:00", "timeZone": "America/New_York" }, "iCalUID": "string", "sequence": 0, "attendees": [ { "email": "example@gmail.com", "displayName": "Jane Doe", "responseStatus": "needsAction" } ], "reminders": { "useDefault": true }, "eventType": "default" } } ``` {% endtab %} {% tab title="401: Unauthorized Invalid/Missing API key" %} ```json { "error": "Unauthorized. Invalid API key." } ``` {% endtab %} {% tab title="404: Not Found Account Not Found. Invalid accountId" %} ```json { "success": false, "error": "Invalid account id. Account Not Found", "code": 404 } ``` {% endtab %} {% tab title="404: Not Found Calendar Not Found" %} ```json { "success": false, "error": "Not Found", "code": 404 } ``` {% endtab %} {% tab title="400: Bad Request Missing required fields" %} ```json { "errors": [ { "value": { "description": "example", "startDate": "2023-03-06T23:12:25.069Z", "endDate": "2023-03-06T23:42:25.069Z", "timeZone": "America/New_York", "location": { "street": "712 Applesauce Rd", "city": "Austin", "state": "TX", "zipCode": "73301", "country": "USA" }, "attendees": [ { "name": "Jane Doe", "email": "example@gmail.com" } ] }, "msg": "eventData.title is required and must be a string", "param": "eventData", "location": "body" } ] } ``` {% endtab %} {% endtabs %} ### **Event Data Object Example**: ```json { "title": "Example Event", // String - Required. "description": "example", // String - Required. "startDate": "2023-03-06T22:51:08.434Z", // RFC3339 timestamp - Required. "endDate": "2023-03-06T23:21:08.434Z", // RFC3339 timestamp - Required. "timeZone": "America/New_York", // IANA Time Zone format - Optional. "location": { "street": "712 Applesauce Rd", "city": "Austin", "state": "TX", "zipCode": "73301", "country": "USA" }, // Object - Optional. (required when creating an event with a physocal location) "attendees": [ { "name": "Jane Doe", "email": "example@gmail.com" } ] // Required. } ``` ### Event Location Object Example: ```json { "street": "712 Applesauce Rd", // String - Required. "city": "Austin", // String - Required. "state": "TX", // String - Required. "zipCode": "73301", // String - Required. "country": "USA" // String - Required. }, ``` ### Attendee Object Example: ```json { "name": "Jane Doe", // String - Required. "email": "example@gmail.com" // String - Required. } ``` ### Event Conferencing Object: ```typescript { "provider": string, // Required. Possible values: "google-meet", "zoom" "accountId": string, // Optional. - Only Required if provider = zoom. This is the ID for the connected Zoom account in Pyas. "waitingRoom": boolean // Optional. - Only Required if provider = zoom } ``` ### Event Data With Google Meet Conferencing Example: ```json { "title": "Example Event 2", "description": "example", "startDate": "2023-03-06T22:51:08.434Z", "endDate": "", "conferencing": { "provider": "google-meet" }, "timeZone": "America/New_York", "attendees": [ { "name": "Jane Doe", "email": "example@gmail.com" } ] } ``` ### Recurrence Object: ```typescript { type: string // daily, weekly, or monthly - Required. interval: number|string // Define the interval at which the meeting should recur. (ex. 2 for every two weeks with type of weekly) - Required. startDate?: string // the dateTime of when the recurring meeting will start (used for Microsoft Outlook only) endDate?: string // the dateTime of when the recurring meeting will end dayOfMonth?: number|string // day of month for a monthly meeting. 1 - 31 (ex. 15 for the 15th of every month) daysOfWeek?: Array // days of week for a weekly meeting type (ex. ['monday', 'wednesday']) month?: number|string // The month in which the event occurs. This is a number from 1 to 12. (Microsoft and Google only) } ``` Here's an example of a recurrence object for a meeting that repeats weekly every Wednesday: 
{
    "type": "weekly",
    "interval": 1,
    "daysOfWeek": ["wednesday"],
    "endDate": "2023-08-01T22:26:39.109Z"
}
## Event Data Meta Object Example More request body fields from the official Google Docs can be found here: Simply include the extra fields you need to `eventData.meta`. If you need to store custom properties to the event, you can do so by adding a nested [**extendedProperties** ](https://developers.google.com/calendar/api/guides/extended-properties)object to `eventData.meta`. Please see the [example below](#example-eventdata-with-meta-object). Note: `eventData.meta` should only be used to include fields that aren't already a part of the standard body fields in the ***eventData*** object. Also note that there won't be a **meta** field on the event body/data returned in the response. Instead, any properties/fields that were sent in `eventData.meta` will be spread onto the event body that gets returned in the response. ```typescript { birthdayProperties?: { type: string //anniversary, birthday, custom, other, self } colorId?: string eventType?: string // birthday, default, focusTime, fromGmail, outOfOffice, workingLocation focusTimeProperties?: { autoDeclineMode?: string // declineNone, declineAllConflictingInvitations, declineOnlyNewConflictingInvitations chatStatus?: string // available, doNotDisturb declineMessage?: string } guestsCanModify?: boolean // false by default guestsCanInviteOthers?: boolean //true by default guestsCanSeeOtherGuests?: boolean //true by default visibility?: string // default, private, public transparency?: string // opaque, transparent // etc... } ``` ### Example EventData with Meta Object ```json { "title": "Test Event w/ Metadata", "description": "example with metadata", "startDate": "{{start_time}}", "endDate": "{{end_time}}", "timeZone": "America/New_York", "location": { "street": "712 Applesauce Rd", "city": "Austin", "state": "TX", "zipCode": "73301", "country": "USA" }, "attendees": [ { "name": "Jane Doe", "email": "user@gmail.com" } ], "meta": { "guestsCanModify": true, "guestsCanInviteOthers": false, "extendedProperties": { "private": { "petsAllowed": "yes", //more private extended properties } } } } ``` ## Update Event `PATCH` `https://api.pyas.io/google/events/{id}` Updates an Existing Event #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------ | | {id}\* | String | The event ID | #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API Key | #### Request Body | Name | Type | Description | | -------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | accountId\* | String | The user's Pyas account id. This is returned when you connect an account to Pyas. | | calendarId\* | String | The Google calendar id | | eventData\* | Object | Event data object with the fields to update. See the [**Example Update Event Date Object**](#update-event-data-object-example) below. | | eventData.meta | Object | Optional. Additional fields to include in the update request. See the [Event Data Meta Object Example](#event-data-meta-object-example) above. | {% tabs %} {% tab title="200: OK Event updated successfully" %} ```json { "success": true, "data": { "kind": "calendar#event", "etag": "\"000000000\"", "id": "ae019d68ac9b4ff6823d5c3b81d761f9", "status": "confirmed", "htmlLink": "string", "created": "2023-03-08T18:34:01.000Z", "updated": "2023-03-08T18:46:43.015Z", "summary": "Interview", "description": "Interview with Elon", "location": "712 Applesauce Rd Austin, TX 73301", "creator": { "email": "example@gmail.com", "self": true }, "organizer": { "email": "example@gmail.com", "self": true }, "start": { "dateTime": "2023-03-08T15:16:40-05:00", "timeZone": "America/New_York" }, "end": { "dateTime": "2023-03-08T15:46:40-05:00", "timeZone": "America/New_York" }, "iCalUID": "string", "sequence": 1, "attendees": [ { "email": "example@gmail.com", "displayName": "Jane Doe", "responseStatus": "needsAction" } ], "reminders": { "useDefault": true }, "eventType": "default" } } ``` {% endtab %} {% tab title="404: Not Found Calendar Not Found" %} ```json { "success": false, "error": "Not Found", "code": 404 } ``` {% endtab %} {% tab title="404: Not Found Account Not Found/Invalid Account Id" %} ```json { "success": false, "error": "Invalid account id. Account Not Found", "code": 404 } ``` {% endtab %} {% tab title="400: Bad Request Missing eventData" %} ```json { "errors": [ { "msg": "eventData is required.", "param": "eventData", "location": "body" }, { "msg": "eventData must be an object", "param": "eventData", "location": "body" }, { "msg": "Invalid value", "param": "eventData", "location": "body" } ] } ``` {% endtab %} {% endtabs %} ### Update Event Data Object Example: ```json { "title": "Interview", "description": "Interview with Elon", "startDate": "2023-03-06T22:51:08.434Z", "endDate": "2023-03-06T23:21:08.434Z", "timeZone": "America/New_York" } ``` ## Delete Event `DELETE` `https://api.pyas.io/google/events/{id}` Deletes an existing event #### Path Parameters | Name | Type | Description | | -------------------------------------- | ------ | ------------ | | {id}\* | String | The event ID | #### Query Parameters | Name | Type | Description | | -------------------------------------------- | ------ | --------------------------------------------------------------------------------- | | accountId | String | The user's Pyas account id. This is returned when you connect an account to Pyas. | | calendarId\* | String | The Google calendar ID | #### Headers | Name | Type | Description | | ------------------------------------------- | ------ | ----------- | | x-api-key\* | String | API Key | {% tabs %} {% tab title="204: No Content Event was deleted successfully" %} ```javascript { // Response } ``` {% endtab %} {% endtabs %}