🕢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)

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

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

$filter

String

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

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": "[email protected]"
                        }
                    }
                ],
                "organizer": {
                    "emailAddress": {
                        "name": "John Doe",
                        "address": "[email protected]"
                    }
                },
                "onlineMeeting": null,
                "[email protected]": "https://graph.microsoft.com/v1.0/users('[email protected]')/calendars('some-id')/$ref",
                "[email protected]": "https://graph.microsoft.com/v1.0/users('[email protected]')/calendars('some-id')"
            }
        ],
        "nextPageToken": null
    }
}

{
    "errors": [
        {
            "msg": "an account id is required.",
            "param": "accountId",
            "location": "query"
        },
        {
            "msg": "a calendar id is required.",
            "param": "calendarId",
            "location": "query"
        }
    ]
}

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

{
    "errors": [
        {
            "msg": "calendar id is required",
            "param": "calendarId",
            "location": "query"
        },
        {
            "msg": "calendar id must be a string",
            "param": "calendarId",
            "location": "query"
        }
    ]
}

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

The event data. See the Required Event Data Object 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

eventData.attendees

Array

Array of Attendee Objects

eventData.conferencing

Object

An Event Conferencing Object

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 below.

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": "[email protected]",
            "self": true
        },
        "organizer": {
            "email": "[email protected]",
            "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": "[email protected]",
                "displayName": "Jane Doe",
                "responseStatus": "needsAction"
            }
        ],
        "reminders": {
            "useDefault": true
        },
        "eventType": "default"
    }
}

{
    "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": "[email protected]"
                    }
                ]
            },
            "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": "[email protected]"
          }
         
      ] // 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": "[email protected]" // 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": "[email protected]"
            }
        ]
        
}

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": "[email protected]"
            }
        ]
        
}

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

More request body fields from the official Microsoft Docs can be found here: https://learn.microsoft.com/en-us/graph/api/resources/event?view=graph-rest-1.0

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": "[email protected]"
            }
           
        ],
        "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": "[email protected]"
            }
           
        ],
        "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

Event data object with the fields to update. See the Example Update Event Date Object below.

eventData.meta

Object

Optional. Additional fields to include in the update request. See the Event Data Meta Object above.

{
    "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": "[email protected]"
                }
            }
        ],
        "organizer": {
            "emailAddress": {
                "name": "John Doe",
                "address": "[email protected]"
            }
        },
        "onlineMeeting": null
    }
}

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

PreviousCalendars NextZoom

Last updated 1 year ago

hashtagGet All Events From a Calendar

hashtagQuery Parameters

hashtagHeaders

hashtagGet Event by ID

hashtagPath Parameters

hashtagQuery Parameters

hashtagHeaders

hashtagCreate Event

hashtagHeaders

hashtagRequest Body

hashtagEvent Data Object Example:

hashtagEvent Location Object Example:

hashtagAttendee Object Example:

hashtagEvent Conferencing Object:

hashtagEvent Data With Zoom Conferencing Example:

hashtagEvent Data With Teams Conferencing Example:

hashtagRecurrence Object:

hashtagEvent Data Meta Object Example

hashtagExample EventData with Meta Object

hashtagExample EventData with Extended Properties

hashtagUpdate Event

hashtagPath Parameters

hashtagHeaders

hashtagRequest Body

hashtagUpdate Event Data Object Example:

hashtagDelete Event

hashtagPath Parameters

hashtagQuery Parameters

hashtagHeaders

Get All Events From a Calendar

Query Parameters

Headers

Get Event by ID

Path Parameters

Query Parameters

Headers

Create Event

Headers

Request Body

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

Path Parameters

Headers

Request Body

Update Event Data Object Example:

Delete Event

Path Parameters

Query Parameters

Headers