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 Zoom Conferencing Example:
  • Event Data With Teams Conferencing Example:
  • Recurrence Object:
  • Event Data Meta Object Example
  • Example EventData with Meta Object
  • Example EventData with Extended Properties
  • Update Event
  • Update Event Data Object Example:
  • Delete Event
  1. REST API Reference
  2. Microsoft Outlook

Events

Microsoft Outlook Calendar Events

Get All Events From a Calendar

GET https://api.pyas.io/microsoft/events

Query Parameters

Name
Type
Description

calendarId*

String

The id of the Microsoft Outlook calendar

accountId*

String

The user's Pyas account id. This is returned when you connect an account to Pyas.

startDate

Date String

Filter events from a start date

(ex: 01-01-2022)

endDate

Date String

Filter events up to an end date

(ex: 01-01-2023)

search

String

Free text search to filter events based on the subject field.

nextPageToken

String

Token string used to get the next page of results (paginate)

maxResults

Integer

Max number of results to

return per page

$expand

String

$filter

String

Headers

Name
Type
Description

x-api-key*

String

API key

{
    "success": true,
    "data": {
        "count": 1,
        "events": [
            {
                "@odata.etag": "W/\"some-id\"",
                "id": "some-event-id",
                "createdDateTime": "2023-04-06T21:48:43.8341359Z",
                "lastModifiedDateTime": "2023-04-06T21:48:44.2375882Z",
                "changeKey": "some-key",
                "categories": [],
                "transactionId": null,
                "originalStartTimeZone": "UTC",
                "originalEndTimeZone": "UTC",
                "iCalUId": "some-id",
                "reminderMinutesBeforeStart": 15,
                "isReminderOn": true,
                "hasAttachments": false,
                "subject": "Example Event",
                "bodyPreview": "This is an appoinemtment test",
                "importance": "normal",
                "sensitivity": "normal",
                "isAllDay": false,
                "isCancelled": false,
                "isOrganizer": true,
                "responseRequested": true,
                "seriesMasterId": null,
                "showAs": "busy",
                "type": "singleInstance",
                "webLink": "https://outlook.live.com/owa/?itemid=some-event-id&exvsurl=1&path=/calendar/item",
                "onlineMeetingUrl": null,
                "isOnlineMeeting": false,
                "onlineMeetingProvider": "unknown",
                "allowNewTimeProposals": true,
                "occurrenceId": null,
                "isDraft": false,
                "hideAttendees": false,
                "responseStatus": {
                    "response": "organizer",
                    "time": "0001-01-01T00:00:00Z"
                },
                "body": {
                    "contentType": "html",
                    "content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nThis is an appoinemtment test\r\n</body>\r\n</html>\r\n"
                },
                "start": {
                    "dateTime": "2023-04-06T21:48:42.3800000",
                    "timeZone": "UTC"
                },
                "end": {
                    "dateTime": "2023-04-06T22:18:42.3800000",
                    "timeZone": "UTC"
                },
                "location": {
                    "displayName": "712 Applesauce Rd",
                    "locationUri": "",
                    "locationType": "default",
                    "uniqueId": "712 Applesauce Rd",
                    "uniqueIdType": "private",
                    "address": {
                        "street": "712 Applesauce Rd",
                        "city": "Austin",
                        "state": "TX",
                        "countryOrRegion": "USA",
                        "postalCode": "73301"
                    },
                    "coordinates": {}
                },
                "locations": [
                    {
                        "displayName": "712 Applesauce Rd",
                        "locationUri": "",
                        "locationType": "default",
                        "uniqueId": "712 Applesauce Rd",
                        "uniqueIdType": "private",
                        "address": {
                            "street": "712 Applesauce Rd",
                            "city": "Austin",
                            "state": "TX",
                            "countryOrRegion": "USA",
                            "postalCode": "73301"
                        },
                        "coordinates": {}
                    }
                ],
                "recurrence": null,
                "attendees": [
                    {
                        "type": "required",
                        "status": {
                            "response": "none",
                            "time": "0001-01-01T00:00:00Z"
                        },
                        "emailAddress": {
                            "name": "Jane Doe",
                            "address": "example@email.com"
                        }
                    }
                ],
                "organizer": {
                    "emailAddress": {
                        "name": "John Doe",
                        "address": "outlook_user-id@outlook.com"
                    }
                },
                "onlineMeeting": null,
                "calendar@odata.associationLink": "https://graph.microsoft.com/v1.0/users('outlook_some-id@outlook.com')/calendars('some-id')/$ref",
                "calendar@odata.navigationLink": "https://graph.microsoft.com/v1.0/users('outlook_some-id@outlook.com')/calendars('some-id')"
            }
        ],
        "nextPageToken": null
    }
}
{
    "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
}

Get Event by ID

GET https://api.pyas.io/microsoft/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 Microsoft Outlook 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/microsoft/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 Microsoft 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.
      "phone": "" // string - Optional. Use if the meeting will be over phone
      "onlineMeetingUrl": "" // string - Optional. (Use this if you have an already generated conferencing url, like a Google Meet url for example)
        
}

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: "zoom", "teams"
    "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 Zoom Conferencing Example:

{
        "title": "Example Event 2",
        "description": "example",
        "startDate": "2023-03-06T22:51:08.434Z",
        "endDate": "",
        "conferencing": {
            "provider": "zoom",
            "accountId": "some-account-id",
            "waitingRoom": true
        },
        "timeZone": "America/New_York",
        "attendees": [
            {
                "name": "Jane Doe",
                "email": "example@gmail.com"
            }
        ]
        
}

Event Data With Teams Conferencing Example:

**Important: In order for Microsoft Teams conferencing to be automatically generated with the calendar event, users must have Teams enabled as their Default Online Meeting Provider or be part of their Allowed Online Meeting Providers list in Outlook.

{
        "title": "Example Event 2",
        "description": "example",
        "startDate": "2023-03-06T22:51:08.434Z",
        "endDate": "",
        "conferencing": {
            "provider": "teams"
        },
        "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

Simply include the extra fields you need to eventData.meta like in the example below.

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.

{
    importance?: string // low, normal, high
    isAllDay?: boolean
    isCancelled?: boolean
    responseRequested?: boolean // true by default
    // 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@outlook.com"
            }
           
        ],
        "meta": {
            "importance": "high"
        }
        
}

Example EventData with Extended Properties

{
        "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@outlook.com"
            }
           
        ],
        "meta": {
            "importance": "high",
            "singleValueExtendedProperties": [
                {
                    "id": "String {e97a3fd8-5391-4d50-887d-5dfaa93de27b} Name extendedProperties",
                    "value": "test"
                }
            ],
            "multiValueExtendedProperties": [
                 {
                   "id":"StringArray {66f5a359-4659-4830-9070-00050ec6ac6e} Name Recreation",
                   "value": ["Food", "Hiking", "Swimming"]
                 }
              ]
        }
        
}

Update Event

PATCH https://api.pyas.io/microsoft/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 Microsoft calendar id

eventData*

Object

eventData.meta

Object

{
    "success": true,
    "data": {
        "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#us...",
        "@odata.etag": "W/\"+K9fsQXPJUK+WQAiVksmowAAKw/Ytw==\"",
        "id": "AQMkADAwATNiZmYAZC01ZGQAN\...",
        "createdDateTime": "2023-04-25T19:17:48.2318596Z",
        "lastModifiedDateTime": "2023-04-25T19:17:51.5235851Z",
        "changeKey": "+K9fsQXPJUK+WQAiVkYtw==",
        "categories": [],
        "transactionId": null,
        "originalStartTimeZone": "UTC",
        "originalEndTimeZone": "UTC",
        "iCalUId": "040000008200E00074C5B7101A82E008000000002...",
        "reminderMinutesBeforeStart": 15,
        "isReminderOn": true,
        "hasAttachments": false,
        "subject": "Test Appointment",
        "bodyPreview": "This is an appoinemtment test",
        "importance": "normal",
        "sensitivity": "normal",
        "isAllDay": false,
        "isCancelled": false,
        "isOrganizer": true,
        "responseRequested": true,
        "seriesMasterId": null,
        "showAs": "busy",
        "type": "singleInstance",
        "webLink": "https://outlook.live.com/owa/?itemid=AQMkADA...",
        "onlineMeetingUrl": null,
        "isOnlineMeeting": false,
        "onlineMeetingProvider": "unknown",
        "allowNewTimeProposals": true,
        "occurrenceId": null,
        "isDraft": false,
        "hideAttendees": false,
        "responseStatus": {
            "response": "organizer",
            "time": "0001-01-01T00:00:00Z"
        },
        "body": {
            "contentType": "html",
            "content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r\n</head>\r\n<body>\r\nThis is an appoinemtment test\r\n</body>\r\n</html>\r\n"
        },
        "start": {
            "dateTime": "2023-04-25T19:17:44.8510000",
            "timeZone": "UTC"
        },
        "end": {
            "dateTime": "2023-04-25T19:47:44.8510000",
            "timeZone": "UTC"
        },
        "location": {
            "displayName": "712 Applesauce Rd",
            "locationUri": "",
            "locationType": "default",
            "uniqueId": "712 Applesauce Rd",
            "uniqueIdType": "private",
            "address": {
                "street": "712 Applesauce Rd",
                "city": "Austin",
                "state": "TX",
                "countryOrRegion": "USA",
                "postalCode": "73301"
            },
            "coordinates": {}
        },
        "locations": [
            {
                "displayName": "712 Applesauce Rd",
                "locationUri": "",
                "locationType": "default",
                "uniqueId": "712 Applesauce Rd",
                "uniqueIdType": "private",
                "address": {
                    "street": "712 Applesauce Rd",
                    "city": "Austin",
                    "state": "TX",
                    "countryOrRegion": "USA",
                    "postalCode": "73301"
                },
                "coordinates": {}
            }
        ],
        "recurrence": null,
        "attendees": [
            {
                "type": "required",
                "status": {
                    "response": "none",
                    "time": "0001-01-01T00:00:00Z"
                },
                "emailAddress": {
                    "name": "Jane Doe",
                    "address": "example@gmail.com"
                }
            }
        ],
        "organizer": {
            "emailAddress": {
                "name": "John Doe",
                "address": "user@outlook.com"
            }
        },
        "onlineMeeting": null
    }
}
{
    "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/microsoft/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 Microsoft Outlook calendar ID

Headers

Name
Type
Description

x-api-key*

String

API Key

{
    // Response
}
PreviousCalendarsNextZoom

Last updated 3 months ago

query to include single or multi value extended properties on events that have an extended property. Ex: $expand=singleValueExtendedProperties($filter=id eq '{id_value}')

query to filter events by single or multi extended properties. Ex: $filter=singleValueExtendedProperties/Any(ep: ep/id eq '{id_value}' and ep/value eq '{property_value}'

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 Microsoft Docs can be found here:

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

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

🕢
https://learn.microsoft.com/en-us/graph/api/resources/event?view=graph-rest-1.0
More Info
More Info
Event Data Object
Event Location Object
Attendee Objects
Event Conferencing Object
Recurrence Object
Example Update Event Date Object
Event Data Meta Object