Pyas Docs
  • 📖Getting Started With Pyas
  • Fundamentals
    • 📦Pyas Apps
    • 📦Provider Apps
    • 🔒Pyas Auth vs Native Auth
    • 🛠️Getting set up
      • 🧑Inviting Team Members
      • 📦Creating an App
      • 🔒Setup Authentication
        • Pyas Auth
        • Native Auth
          • Create a Google App
          • Create an Azure App
          • Create a Zoom App
        • 🔗Connect an Account
      • 🪝Create Webhooks
    • ✨Connected Accounts
      • Zoom
  • REST API Reference
    • Introduction
    • API Authentication
    • Google Calendar
      • 🔒Auth
      • 🗓️Calendars
      • 🕢Events
    • Microsoft Outlook
      • 🔒Auth
      • 🗓️Calendars
      • 🕢Events
    • Zoom
      • 🔒Auth
      • 🕢Meetings
  • Get the Postman Collection
Powered by GitBook
On this page
  • Get All Events From a Calendar
  • Get Event by ID
  • Create Event
  • Event Data Object Example:
  • Event Location Object Example:
  • Attendee Object Example:
  • Event Conferencing Object:
  • Event Data With Google Meet Conferencing Example:
  • Recurrence Object:
  • Event Data Meta Object Example
  • Example EventData with Meta Object
  • Update Event
  • Update Event Data Object Example:
  • Delete Event
  1. REST API Reference
  2. Google Calendar

Events

Google Calendar 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:

  • "birthday": Special all-day events with an annual recurrence.

  • "default": Regular events.

  • "focusTime": Focus time events.

  • "fromGmail": Events from Gmail.

  • "outOfOffice": Out of office events.

  • "workingLocation": Working location events.

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:

  • "startTime": Order by the start date/time (ascending). This is only available when querying single events (i.e. the parameter singleEvents is True)

  • "updated": Order by last modification time (ascending).

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.

Headers

Name
Type
Description

x-api-key*

String

API key

{
    "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"
            },
        ]
    }
}
{
    "error": "Unauthorized. Invalid API key."
}
{
    "errors": [
        {
            "msg": "a calendar id is required.",
            "param": "calendarId",
            "location": "query"
        }
    ]
}
{
    "errors": [
        {
            "msg": "an account id is required.",
            "param": "accountId",
            "location": "query"
        }
    ]
}
{
    "errors": [
        {
            "msg": "an account id is required.",
            "param": "accountId",
            "location": "query"
        },
        {
            "msg": "a calendar id is required.",
            "param": "calendarId",
            "location": "query"
        }
    ]
}
{
    "success": false,
    "error": "Invalid account id. Account Not Found",
    "code": 404
}
{
    "success": false,
    "error": "Not Found",
    "code": 404
}

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.

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

{
    "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"
        }
    }
}
{
    "error": "Unauthorized. Invalid API key."
}
{
    "errors": [
        {
            "msg": "calendar id is required",
            "param": "calendarId",
            "location": "query"
        },
        {
            "msg": "calendar id must be a string",
            "param": "calendarId",
            "location": "query"
        }
    ]
}
{
    "success": false,
    "error": "Not Found",
    "code": 404
}
{
    "success": false,
    "error": "Invalid account id. Account Not Found",
    "code": 404
}

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

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

eventData.attendees

Array

eventData.conferencing

Object

eventData.phone

String

Phone number

eventData.phonePin

String

Optional pin if one is required to join the meeting

eventData.recurrence

Object

eventData.meta

Object

Optional. Use this to add additional/extra event body fields.

{
    "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"
    }
}
{
    "error": "Unauthorized. Invalid API key."
}
{
    "success": false,
    "error": "Invalid account id. Account Not Found",
    "code": 404
}
{
    "success": false,
    "error": "Not Found",
    "code": 404
}
{
    "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"
        }
    ]
}

Event Data Object Example:

{
      "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:

{
    "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:

{
    "name": "Jane Doe", // String - Required.
    "email": "example@gmail.com" // String - Required.
}

Event Conferencing Object:

{
    "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:

{
        "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:

{
    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<string> // 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

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.

{
    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

{
        "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

eventData.meta

Object

{
    "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"
    }
}
{
    "success": false,
    "error": "Not Found",
    "code": 404
}
{
    "success": false,
    "error": "Invalid account id. Account Not Found",
    "code": 404
}
{
    "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"
        }
    ]
}

Update Event Data Object Example:

{
        "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

{
    // Response
}
PreviousCalendarsNextMicrosoft Outlook

Last updated 3 months ago

The event data. See the Required example below.

Location object - See the example

Array of

An

Recurrence object for recurring events. See the below.

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 object to eventData.meta. Please see the .

Event data object with the fields to update. See the below.

Optional. Additional fields to include in the update request. See the above.

🕢
https://developers.google.com/calendar/api/v3/reference/events/insert#request-body
extendedProperties
example below
See possible filters list below.
Event Data Object
Event Location Object
Attendee Objects
Event Conferencing Object
Recurrence Object
Example Update Event Date Object
Event Data Meta Object Example