# Getting Started With Pyas
Here, you will find everything you need to get started with Pyas and building out calendar integrations using our API.
## Overview
Pyas makes it easy to integrate with Google Calendar, Outlook Calendar, and Zoom. Using our API will significantly cut down your development time and help get your product to market faster.
## Calendar Providers
#### Google Calendar
We support Google Calendar. With our API, you can easily add Google calendar integrations into your app. You'll be able to view calendars, and perform CRUD operations to calendar events.
#### Outlook Calendar
We support Microsoft's Outlook Calendar. With our API, you can easily add Outlook calendar integrations into your app. You'll be able to view calendars, and perform CRUD operations to calendar events.
## Conferencing
#### Google Meet
When you integrate Google Calendar, you'll be able to use Google Meet as a conferencing option to Google Calendar events that you create. No extra configuration is required.
#### Zoom
We support Zoom conferencing. With our API, you can easily add Zoom integration into your app. You'll be able to perform CRUD operations to Zoom meetings. You'll also be able to add Zoom as a conferencing option to both Google and Outlook Calendar events that you create.
## Quick links
{% content-ref url="/pages/41xaBZLet84aVq1sdfLa" %}
[Pyas Apps](/fundamentals/pyas-apps)
{% endcontent-ref %}
{% content-ref url="/pages/peZw67vEKuh0GMaJXLkJ" %}
[Provider Apps](/fundamentals/provider-apps)
{% endcontent-ref %}
# Pyas Apps
What are Pyas Apps?
## Apps
When you sign up for Pyas, in order to start using our API, you must create an App. But what is a Pyas App? Think of a Pyas App as an isolated environment for your connected accounts. Each app you create will have its own Client ID and Client Secret. Additionally, you'll be able to create API keys and webhooks for each app. Aside from your organization and personal settings, everything in Pyas is associated with an app. A Pyas App has a one-to-many relationship with connected accounts, webhooks, api keys, etc.
Unless you're on the developer plan, you'll be able to create multiple Pyas Apps. We recommend creating an app for each of your product environments (Dev, Staging & Prod). This helps keep your data separated. When connecting accounts, you'll have to authenticate against each Pyas App.
# Provider Apps
What are Provider Apps?
## Apps
Provider apps are important when you need to completely customize your users' experience when authenticating/connecting their Google, Outlook, and Zoom accounts. Creating a provider app allows you to put your company name and logo on the consent screens. When creating provider apps, we recommend you create one for each of your environments (Dev, Staging & Prod). Then, you can create a Pyas App that corresponds to each one of those provider app environments.
# Pyas Auth vs Native Auth
What are the authentication options?
## Pyas Authentication
When you sign up for Pyas and create an app, **Pyas Authentication** is enabled by default. This helps you get up and running quickly and allows you to start connecting Google, Outlook, and Zoom accounts in a matter of minutes. The consent screens that your user will see when you try to connect to their accounts, using the Pyas Authentication option, will display the Pyas name and logo. Overall, this is the quickset option to get you started and add calendar integrations into your app.
## Native Authentication
The Native Authentication option is recommended when you want to completely customize the authentication experience for your users. Your users will authenticate directly in your app without redirecting them to Pyas. They will never know that you're using Pyas behind the scenes to handle your calendar integration needs. You will have full control over the process, look and feel of the login/consent experience.
Keep in mind that using the native authentication option requires you to set up provider apps with the third-party providers you use (Google, Microsoft or Zoom). This is more complicated than using the Pyas Authentication option and takes a bit longer to get setup. Also, keep in mind that you will have to get your provider apps verified by Google, Microsoft, or Zoom (whichever providers you use). If you don't require any customization and don't mind your users seeing the Pyas name and logo on the consent screens, use the simpler Pyas Authentication option.
# Getting set up
These 6 steps will help you get up and running with Pyas.
Step1: Creating your organization
Register for a [Pyas account](https://www.app.pyas.io/auth/register).
You'll be asked to provide your full name, organization name and email (this should be the email you plan to use for your organization. It cannot be changed.)
Step 2: Inviting your team
See the [Inviting Members](/fundamentals/getting-set-up/inviting-team-members) section.
Step 3: Create a Pyas App
See the [Creating an App](/fundamentals/getting-set-up/creating-an-app) section.
Step 4: Configure Authentication
There are 2 options for authenticating users; Pyas Auth and Native Auth.
The quickest way to start connecting accounts is to use the Pyas Auth option.
See the [Setup Authentication](/fundamentals/getting-set-up/setup-authentication) section for more info.
Step 5: Generate API Keys
In order to start using our API, you must create API keys. See the [**API Authentication**](/rest-api-reference/api-authentication) section for more info.
Step 6: Connect an Account
You should now be ready to start connecting accounts and using the API.
# Inviting Team Members
Invite your team.
## First, determine which role you want each member to have.
When inviting team members to your organization, there are 2 role options to choose from.
| Role | Capabilities |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Admin |
Have full App access (create, read, update, delete)
Can create, update & delete API keys
Can create, update, & delete webhooks
Can configure app authentication
Can manage other team members (invite & revoke/enable member access)
Can manage billing & subscription
|
| Developer |
Can create, read, and update apps
Can create API keys
Can only update/delete API keys that they create
Can create webhooks
Can only update/delete webhooks that they create
Can configure app authentication
Can view/see team members
|
### Invite a Team Member
1. Go to the **Settings** tab on the left menu bar.
2. Click on the **Team Members** tab on the settings page.
3. Click the **Invite a Team Member** button.
4. Fill in the invitation form modal that opens up after you click the button in step 3. Note: the Developer role is selected by default. Feel free to select Admin if you're inviting an admin user.
5. Click the green **Invite** button.
An invitation email will be sent to the user and the invitation status will be Pending until they accept your invitation and join your organization.
# Creating an App
You must create an app in order to use Pyas and connect accounts.
### Create an App
1. Login to your Pyas account.
2. Click on the **Apps** tab on the left menu bar.
3. Click on the **New App** button
4. Fill in the form fields for creating the app and click **Create App**
Your new app is created and you should now see the app screen like in the image below.
# Setup Authentication
There are 2 Authentication options.
Pyas Authentication
See the [Pyas Auth](/fundamentals/getting-set-up/setup-authentication/pyas-auth) section.
Native Authentication
See the [Native Auth](/fundamentals/getting-set-up/setup-authentication/native-auth) section.
For More details about these 2 authentication options, see the [Pyas Auth vs Native Auth](/fundamentals/pyas-auth-vs-native-auth) section.
# Pyas Auth
Configure Pyas Authentication
After you create an app, you should go ahead and configure the authentication settings. Below are the steps to configure Pyas Auth.
1. From your app view, click on the **Settings** tab.
2. Then, click on the **Authentication** tab.
By default, the Pyas Auth option is enabled for all providers.
3. The next thing you'll need to do is update the redirect URL for each of the providers. Pyas will redirect users to that URL after they allow access on the consent screens. A code param will be passed in the URL, which you will need in order to complete the account connections.
4. After you add the redirect URLs, click the **Save Pyas Auth Settings** button.
Your Pyas Auth configuration should now be saved.
# Native Auth
Configure Native Authentication
Use Native Auth if you want your company name and logo on the OAuth consent screen instead of Pyas.
{% hint style="info" %}
Note: If you decide to switch from the Pyas Auth to Native Auth, or vise versa, you will need to re-authenticate/connect each account. If you want to switch authentication methods, we recommend you create a new Pyas App.
{% endhint %}
In order to use Native Auth, you need to create provider apps for each provider that you plan to use.
# Create a Google App
Below are the steps for creating a Google App.
## Create a New Project
1. Go to
You'll see one of these New Project screen options depending on whether your google account is part of an organization (google workspace) or not.
***New Project view for personal Google accounts***
***New Project view for Google workspace accounts***
2. Add a name for your project.
3. For google workspace accounts, select your project's **Organization** and **Location**.
4. Click on the **CREATE** button.
Once your new project has been created, you'll get a notification that looks like this:
5. Click the **SELECT PROJECT** link in the notification.
## Enable APIs for Your Project
1. From the Google Cloud dashboard, go to **APIs and Services** on the left menu and then click on **Enabled APIs and Services**.
2. Click on **+ ENABLE APIS AND SERVICES**
This should open up the API Library
3. Search for and enable the following APIs
1. **Google Calendar API** - required for reading calendars and performing CRUD operations on calendar events.
2. **Google People API** - required for reading user info such as name and email address.
3. **Admin SDK API** - required for reading room info for calendar events.
## Configure OAuth Screen
After you've enabled all the APIs, you must configure your Google App's OAuth consent screen. This is the page users will see when authenticating/allowing your app access to their Google account.
1. From the Google Cloud dashboard, hover over **APIs & Services** on the left menu. Then click on **OAuth consent screen**
2. For User Type, choose either **Internal** or **External**, depending on your use case.
Choose Internal if your app will only be used by users from your organization. Choose External if you want anyone with a Gmail account to be able to use your app. External apps require verification by Google before you can go to production.
### OAuth Screen Steps
1. Fill out all required info for the OAuth screen.
2. Add `pyas.io` to your **Authorized domains** list
3. Add your developer contact email
4. Click on **SAVE AND CONTINUE**
5. Next, click **ADD OR REMOVE SCOPES**
6. Copy the scopes below and paste them into the **Manually add scopes** textarea.
***Scopes to use:***
```
https://www.googleapis.com/auth/userinfo.email
https://www.googleapis.com/auth/userinfo.profile
openid
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/calendar.freebusy
https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly
https://www.googleapis.com/auth/calendar.calendarlist.readonly
https://www.googleapis.com/auth/calendar.calendars.readonly
```
7. Click **ADD TO TABLE** and then click **UPDATE**
8. Click **SAVE AND CONTINUE**
9. If you selected **External** for the User Type, the next step will be to add test users. Click the **+ADD USERS** button on the Test users screen.
10. Enter up to 100 email addresses for your test users and then click **ADD**.
11. Click **SAVE AND CONTINUE**
12. Review the summary and then click **BACK TO DASHBOARD**
13. When you're ready to go to production with your Google App, click the **PUBLISH APP** button.
### Create Credentials
The next thing you need to do is create OAuth credentials for your app. You will need to provide these credentials to Pyas later so we authenticate your users and access their calendars through our API.
1. From the Google Cloud dashboard, under APIs & Services, click on Credentials.
2. Click on **CREATE CREDENTIALS** and then select **OAuth client ID**
3. For Application Type, select **Web Application**
4. Give your application a name
5. Add authorized redirect URIs.
1. Be sure to add `https://www.app.pyas.io/org/apps/oauth/google/callback` as an authorized redirect URI
2. Also add `https://api.pyas.io/oauth/google/callback` as an authorized redirect URI
3. Add your own redirect URI that you plan on using for your app
6. Click **CRERATE**
7. There should now be a popup with your OAuth credentials. Save them so you can add them to your Pyas account later.
### Add Your Google OAuth Client ID and Client Secret to Pyas
1. Login to your Pyas account
2. Select the Pyas App you will be updating
3. Go to the Pyas App's settings tab
4. Click on Authentication
5. Under **Pyas Authentication**, toggle the **Enable Pyas Auth for Google Accounts** switch off. Then, click the **Save Pyas Auth Settings** button.
6. Scroll down to the **Native Google Authentication** section.
7. Fill in the **Google Oauth Client ID**, **Google Oauth Client Secret**, and **Google Oauth Callback URL.** Note: the Google Oauth Callback URL should be your authorized redirect url that you added back in the **Create Credentials** section of this guide.
8. Once you've added the Google Oauth info, click the **Save Google Settings** button.
**That's it!** You should now be able to use your Google App with Pyas to add Google Calendar integrations into your app.
# Create an Azure App
Below are the steps for creating an Azure App.
## Create a New OAuth Application
1. Create a Microsoft Azure account, if you don't already have one.
2. Login to the Microsoft Azure portal here
3. If you don't already have an active subscription or your account is new, start a new subscription by clicking the **Start** button under ***Start with an Azure free trial.*** Without an active subscription, you won't have access to the resources needed to create your Azure App.
4. From the left menu, click on **Azure Active Directory.**
*\*\*Note:* **Azure Active Directory** is now called **Microsoft Entra ID**
5. From the Active Directory menu, click on **App Registrations** and then click on **New Registration**
### **New App Registration**
1. Add a name for your application
2. Choose the account types you want to support. If you're not sure which type to choose, click on the Help me choose... link.
3. For Redirect URI, select **Web** and add the following URI: `https://api.pyas.io/oauth/microsoft/callback` . We'll add more redirect URIs later.
4. Click on Register
You've now registered your new Azure App. But, we need to configure some things.
### Enable APIs for Your App
1. From the App Registrations page, select your app.
2. Click on **API Permissions** on the left menu and then click on **Add a permission**.
3. Click on **Microsoft Graph** then click on **Delegated Permissions.**
4. Search for and select to following API permissions
* openid
* profile
* offline\_access
* User.Read
* email
* Calendars.Read
* Calendars.ReadBasic
* Calendars.Read.Shared
* Calendars.ReadWrite
* Calendars.ReadWrite.Shared
* Subscription.Read.All
* OnlineMeetings.Read - *Optional. Select this scope if you plan on adding Microsoft Teams conferencing to events*
* OnlineMeetings.ReadWrite - *Optional. Select this scope if you plan on adding Microsoft Teams conferencing to events*
5. Click the **Add Permissions** button.
### Update App Branding
1. From your app page, click on **Branding & Properties** in the left menu.
2. Fill out the form fields for branding (App Name, Logo, Home Page Url, etc..)
3. Click **save.**
### Add More Redirect URIs
1. From your app page, click on **Authentication** in the left menu.
2. Click the **Web** dropdown
3. Click **Add URI**
4. Add `https://www.app.pyas.io/org/apps/oauth/microsoft/callback` as a redirect URI.
5. Add your own redirect URIs as needed
6. Click **Save**
###
### Create OAuth Credentials
1. From your app page, select **Certificates & Secrets** on the left menu
2. Click on **New Client Secret.**
3. Add a description for your secret and select **24 months** as the expiration date.
4. Click **Add**.
5. Copy the secret value
### Add Your Azure App's OAuth Client ID and Client Secret to Pyas
1. Login to your Pyas account
2. Select the Pyas App you will be updating
3. Go to the Pyas App's settings tab
4. Click on Authentication
5. Under **Pyas Authentication**, toggle the **Enable Pyas Auth for Microsoft Accounts** switch off. Then, click the **Save Pyas Auth Settings** button.
6. Scroll down to the **Native Microsoft Authentication** section
7. Paste the client secret value you copied earlier into the **Microsoft Oauth Client Secret** field
8. From your Azure portal, click on **App Registrations**
9. Copy the Application ID of your Azure App
10. Go back to the **Native Microsoft Authentication** section of your Pyas App's Authentication settings
11. Paste your Azure App's Client ID into the **Microsoft Oauth Client ID** field.
12. Add your Azure App's redirect URL into the **Microsoft Callback URL** field.
13. Click **Save Microsoft Settings**
**That's it!** You should now be able to use your Azure App with Pyas to add Outlook Calendar integrations into your app.
Note: Microsoft requires apps that access user data to go through a [domain verification process](https://docs.microsoft.com/en-us/azure/active-directory/develop/howto-configure-publisher-domain), when you're ready to take your app to production.
# Create a Zoom App
Below are the steps for creating a Zoom app.
## Create a Zoom OAuth App
1. Create a Zoom account, if you haven't done so already here:
2. Login to your Zoom account.
3. Go to the [Zoom App Marketplace](https://marketplace.zoom.us/) and click **Develop** in the dropdown menu in the top-right corner of the page.
4. Select **Build App**. A new page will appear displaying the available app types.
5. Click **Create** in the **OAuth** option to continue.
6. Give your Zoom App a Name
7. For App Type, choose **User-managed app**
8. Set the **Would you like to publish this app on Zoom App Marketplace?** toggle to **Yes**
9. Click on **Create**
A new window displaying your new OAuth app will appear.
## App Credentials
When you create your app, Zoom automatically generates the **Client ID** and **Client Secret** for your app. If you had the **Would you like to publish this App on Zoom Marketplace?** toggle set to **Yes,** Zoom generates 2 sets of Client ID and Client Secret. One set is for development and the other set is for production. Use the **development credentials** to build and test your integration. When you're ready to go live, use the **production credentials.**
1. Add a **Redirect URL for OAuth**. The URL should be where you want your users to go after they authenticate against your application. You'll need to do this for both development and production.
2. Add the following URLs:
`https://www.app.pyas.io/org/apps/oauth/zoom/callback`
`https://api.pyas.io/oauth/zoom/callback`
3. Add your own redirect URL to the allow list.
4. Click Continue
## App Information
1. Add your **App Name**
2. Add a **Short Description** for your app
3. Add a **Long Description** for your app
4. Add your **Company Name**
5. Add **Developer Contact** information
Click Continue once you're done adding all of your app information.
## Feature
If you would like to get webhook notifications from Zoom, turn on the Event Subscriptions toggle and then add a URL for your webhook. This is optional.
## Scopes
Add the following scopes, based on your app type.
**For User Level apps**:
* `meeting:read`
* `meeting:write`
* `user:read`
**For Account Level apps**:
* `meeting:master`
* `meeting:read:admin`
* `meeting:write:admin`
* `user:read`
### Add Your Zoom App's OAuth Client ID and Client Secret to Pyas
1. Login to your Pyas account
2. Select the Pyas App you will be updating
3. Go to the Pyas App's settings tab
4. Click on Authentication
5. Under **Pyas Authentication**, toggle the **Enable Pyas Auth for Zoom Accounts** switch off. Then, click the **Save Pyas Auth Settings** button.
6. Scroll down to the **Native Zoom Authentication** section
7. Copy your Zoom App's Client ID and paste it in the **Zoom Oauth Client ID** field.
8. Copy your Zoom App's Client Secret and paste it in the **Zoom Oauth Client Secret** field.
9. Add your Zoom App's redirect URL to the **Zoom Callback URL** field.
10. Click on **Save Zoom Settings**
**That's it!** You should now be able to use your Zoom App with Pyas to add Zoom conferencing to calendar events.
Note: If your app is a User Level app, you have to publish it to the Zoom App Marketplace. See the full tutorial here on creating a Zoom app and publishing it:
# Connect an Account
Connect a Google, Microsoft or Zoom Account
There are 2 ways to connect accounts. The first option is to use the Pyas Dashboard and the second option is to use the REST API.
### Connect an Account from the Pyas Dashboard
This option is great for quickly testing out Pyas.
1. Login to your Pyas account.
2. Click on the **Apps** tab from the left menu bar.
3. Click on the App that you'll be connecting the account to.
4. From the app view under **Accounts**, click the **+ Add Account** button.
5. A modal should open to connect the account. Fill in the **Name** and **Email** fields and select the **Provider** (Google, Microsoft or Zoom)
6. Click on the **Connect Account** button
7. A provider consent screen should open in a new window (Google in this example). Select all the check boxes to allow access to the calendar resources and then click on the **Continue** button.
8. You should now see an Account Connected message. This means the account is connected to Pyas and you can start making API calls for that account.
### Connect an Account using the REST API
This option is recommended and is the best way to start using Pyas to add calendar integrations into your app.
See the [**REST API Reference**](/rest-api-reference/introduction) docs to get started.
# Create Webhooks
Get notified when there are changes/updates to accounts, calendars, and events.
You can use webhooks for 2-way syncing of calendar events. All you need to do is provide Pyas with a webhook URL and select the events you would like to receive notifications for.
**Note**: Using webhooks for 2-way syncing is only supported for Google and Microsoft at this time.
### How it Works
1. You provide a webhook URL.
2. You choose which triggers/notifications you want to receive from Pyas.
3. Pyas sends the notifications in a **POST** request to the webhook URL that you provided.
4. You receive and handle the notifications on your end.
### Pyas will send notifications for the following triggers:
1. **Accounts** - these are for your users' *connected* accounts in Pyas.
* `account.connected`
* `account.inactive`
* `account.deleted`
2. **Calendars** - these triggers currently work for Google only.
* `calendars.created`
* `calendars.deleted`
3. **Calendar Events** - these triggers work for Google and Microsoft.
* `events.created`
* `events.updated`
* `events.deleted`
## The Webhook Request
### Method
POST
### Headers
Each request has the following headers:
```typescript
'x-pyas-account-id': string. // The id of the connected account in Pyas
'x-pyas-webhook-event': string. // The event trigger
'x-provider': string. // The connected account's provider. (Google, Microsoft, or Zoom)
```
### **Body**
The request body for **Calendar Events** notifications will have an events array and looks like this:
```typescript
{
"events": [
{
"calendarId": string. // The calendar id
"eventId": string. // The event id
}
]
}
```
The request body for **Calendar** notifications will have an array of calendar ids and looks like this:
```typescript
{
"calendarIds": [ // calendar id strings ]
}
```
The request body for **Account** notifications is empty.
## Create a new Webhook
1. Login to your Pyas account and click on the **Apps** tab on the left menu.
2. Select the app that you want to set the webhook for.
3. From the app screen, click on the **Webhooks** tab.
4. Click on the **Create Webhook** button.
5. Add your webhook URL. This is a URL that should be setup on your server to receive the webhook notifications from Pyas.
6. Select the triggers that you want. These are events/notifications that Pyas will send to your server.
7. **Click the Create** button.
### That's it!
# Connected Accounts
What are connected accounts?
A connected account is simply an account that you have connected to one of your apps. This can be a Google, Outlook, or Zoom account. Each connected account has a unique ID that you can use to preform CRUD operations.
# Zoom
Connect and Test the Zoom Integrations
This document outlines how users can connect Zoom accounts from the Pyas Dashboard.
For documentation on how to connect Zoom accounts through the Pyas REST API, please refer to [this part of our API reference](/rest-api-reference/zoom).
In order to make integrating with Zoom easier, end-users and developers can use our Zoom for Pyas app. Below are the steps for adding the Zoom for Pyas app, usage, and removing/revoking the Zoom for Pyas app.
This guide assumes you already have at least one Pyas App created in your Pyas Dashboard. If you don't have any apps created, see this guide on [Creating an App](/fundamentals/getting-set-up/creating-an-app).
## Adding the App
* Login to the Pyas dashboard: .
* Click on **Apps** in the left menu bar.
* Click on the app that you want to connect the Zoom account to.
* Under the Accounts tab, click on **+ Add Account**
* In the add account Modal, add a name and the email address for the Zoom account. Then, select Zoom as the provider and then click on **Connect Zoom Account**
* A new window with the Zoom oauth/consent screen will now be open.
* Optionally, check the box that reads: ***Allow this app to use my shared access permissions***
* Click the **Allow** button.
The Zoom account will now be connected and the Zoom for Pyas app is added.
## Usage
Here, we discuss how Pyas is used once a Zoom account has been connected.
1. **Read/List Meetings.**
* To list meetings for a Zoom account from the the dashboard, follow these instructions here: [Get Meetings](#get-meetings).
* To list meetings via the REST API, make a GET request to the following endpoint: `https://api.pyas.io/zoom/meetings` . For more details on using the REST API, visit the documentation here: [API Reference - Get All Meetings](/rest-api-reference/zoom/meetings#get-all-meetings).
2. **Create Meetings**
* To create meetings for a Zoom account from the dashboard, follow these instructions here: [Create Meeting](#create-meeting)
* To create meetings via the REST API, make a POST request to the following endpoint: `https://api.pyas.io/zoom/meetings` . For more details on using the REST API, visit the documentation here: [API Reference - Create a Meeting](/rest-api-reference/zoom/meetings#create-a-meeting).
3. **Update Meetings**
* To update a meeting for a Zoom account from the dashboard, follow these instructions: [Update a Meeting](#update-a-meeting).
* To update meetings via the REST API, make a PATCH request to the following endpoint: `https://api.pyas.io/zoom/meetings` . For more details on using the REST API, visit the documentation here: [API Reference - Update a Meeting](/rest-api-reference/zoom/meetings#update-a-meeting).
4. **Delete Meetings**
* To delete a meeting for a Zoom account from the dashboard, follow these instructions: [Delete a Meeting](#delete-a-meeting).
* To delete meetings via the REST API, make a DELETE request to the following endpoint: `https://api.pyas.io/zoom/meetings` . For more details on using the REST API, visit the documentation here: [API Reference - Delete a Meeting](/rest-api-reference/zoom/meetings#delete-a-meeting).
## **Removing the App**
Users reserve the right to remove the Zoom for Pyas app and revoke Pyas's access to their Zoom account at any time.
When you, the user, revoke access to your account, Pyas will no longer be able to access any of your meetings or personal information. The connected/integrated Zoom account will no longer work.
In order continue using Pyas after access has been revoked, the user/developer will need to reconnect the account following the steps from the **Adding the App** section above in this document.
To remove the Zoom for Pyas app, end-users can follow these simple steps:
1. Login to your Zoom Account and navigate to the Zoom App Marketplace.
2. Click **Manage** >> **Added Apps** or search for the "Zoom for Pyas" app.
3. Click the "Zoom for Pyas" app.
4. Click **Remove**.
## Testing the Zoom Integration
Before you start testing the integration, make sure you have at least one valid/active API key created with ***Read and Write*** scopes. [Read How to Create an API Key](/rest-api-reference/api-authentication)
1. From the Apps page, select the app that has the accounts you would like to test.
2. In the accounts list, click on the "expand" button on an account card to open an Account View modal.
3. An Account View modal will open, and you'll be able to start testing the account connection.
4. Under **Test Account Connection**, follow the straight forward options to **Get Meetings**, **Create Meeting**, **Update a Meeting** and **Delete a Meeting**
#### **Get Meetings**
* To get/read a list of Zoom meetings, simply click the Send Request button and if any meetings exist, they will be displayed in the response section on the right.
#### **Create Meeting**
* Fill in the required fields to create a new meeting and then click the **Send Request** button.
#### **Update a Meeting**
* Copy a meeting ID from the Get Meetings tab
* From the **Update a Meeting** tab, paste in the meeting ID you just copied into the **Meeting ID** field
* Fill in the field(s) that you would like to update
* Click **Send Request**
#### **Delete a Meeting**
* Copy a meeting ID from the list of meetings returned on the **Get Meetings** tab
* Paste the meeting ID into the Meeting ID field in the Delete Meeting tab
* Click **Send Request**
# Introduction
Pyas API Reference
## Overview
The Pyas API allows developers to easily add Google Calendar, Outlook, and Zoom integrations into their apps. Through our API, developers can connect accounts, perform CRUD operations to calendar events on both Google Calendar and Microsoft Outlook, and perform CRUD operations to Zoom meetings.
Our API is based on REST architecture and is accessed via HTTPS. The base URL for all requests is `https://api.pyas.io/` . The complete URL varies depending on the endpoint of the resource being accessed.
All API endpoints are protected and can only be accessed using **API keys**. All API keys are app based and you can generate as many as you need by logging into your Pyas account and going to your app's settings.
API keys must be sent in an `x-api-key` request header.
## Rate Limit
The maximum number of requests that are allowed is based on a 5-minute window timeframe. Each plan has a different limit, as follows:
**Developer Plans**: 100 API calls per 5-minute window *(This is equivalent to 20 calls per minute or 1,200 calls per hour). Note:* *There's a 2,000 monthly API call limit on the Developer Plans.*
**Growth Plans**: 3,000 API calls per 5-minute window *(This is equivalent to 600 calls per minute or 36,000 calls per hour)*
**Scale Plans**: 5,000 API calls per 5-minute window *(This is equivalent to 1,000 calls per minute or 60,000 calls per hour)*
If you exceed this limit, you will get a **429** response that looks like this**:**
```json
{
"message": "Too many requests! You have exceeded the maximum requests allowed per 5-minute window.",
"code": 429,
"error": "Rate limit exceeded"
}
```
The rate limit is based on API Key. If you have multiple API keys, each one will be rate limited to the limits described above.
You may read the `Retry-After` (seconds) or `X-RateLimit-Reset` (date) response headers in order to know when you can restart your requests. In addition, the `X-RateLimit-Remaining` header displays the remaining available requests you can make in the current 5-minute window.
###
# API Authentication
Our API endpoints are protected and require API Keys.
In order to start using the Pyas API, you are required to create API keys.
To authenticate, you will need to pass your API key in the request headers as `x-api-key` .
Note: API Keys are app based. When generating API keys, you generate them for an app. whenever you use your API key, accounts you connect will be associated with the app that the API key belongs to.
## Generate API Keys
1. Login to your Pyas account.
2. Click on the Apps tab to open the Apps page.
3. Select the Pyas App that you want to generate API keys for. If you don't have any apps yet, click on the **+ New App** button to create a new one.
4. Click on the **Settings** tab.
5. Then, click on the **API Keys** tab
6. Click on **Generate New API Key**
7. Add a name for your API key
8. Select an expiration for your API key
9. Select scopes
10. **Click Generate API Key**
Your API Key is generated, and you can now use it to authenticate by passing it in the `x-api-key` request header.
# Google Calendar
Pyas Google Calendar Integration
Pyas allows developers to connect Google accounts via OAuth. Developers don't need to worry about handling refresh tokens because we take care of all of that for you.
Developers will be able to read calendars, create, read, update, and delete events.
# Auth
Connect a Google Account
There are 2 steps for connecting a google account. The first step is to request a Google OAuth URL.
## Get OAuth URL
`GET` `https://api.pyas.io/google/oauth`
#### Query Parameters
| Name | Type | Description |
| --------------------------------------- | ------ | -------------------------- |
| email\* | String | a user's email address |
| state | String | optional application state |
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key\* | String | API key |
{% tabs %}
{% tab title="200: OK OAuth URL was generated successfully" %}
```json
{
"success": true,
"url": "https://accounts.google.com/o/oauth2/v2/auth?..."
}
```
{% endtab %}
{% tab title="400: Bad Request no email address param was provided" %}
```json
{
"errors": [
{
"msg": "Invalid value",
"param": "email",
"location": "query"
},
{
"msg": "a valid email is required.",
"param": "email",
"location": "query"
}
]
}
```
{% endtab %}
{% tab title="400: Bad Request Invalid email address provided" %}
```json
{
"errors": [
{
"value": "bademail",
"msg": "a valid email is required.",
"param": "email",
"location": "query"
}
]
}
```
{% endtab %}
{% tab title="401: Unauthorized Invalid or no api key provided" %}
```json
{
"error": "Unauthorized. Invalid API key."
}
```
{% endtab %}
{% endtabs %}
## Connect Account
The next step is to connect the account. After you get an OAuth URL, you should direct your user to that URL in the browser. The user will then have to authorized/allow access on the OAuth screen. Once the user allows access, Google will redirect the user back to whatever redirect URL that you've set in Pyas. The URL will contain a `code` parameter, which we will use in the connect request.
## Connect Account
`POST` `https://api.pyas.io/google/connect`
Connect Google Account
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key\* | String | API key |
#### Request Body
| Name | Type | Description |
| -------------------------------------- | ------ | ------------------------------- |
| code\* | String | code returned from Google OAuth |
| name\* | String | user's full name |
{% tabs %}
{% tab title="200: OK Account connected successfully" %}
```json
{
"success": true,
"data": {
"account": {
"accountId": "3a39a739-4269-4565-b6ed-97757b5ebffc-po08qu",
"email": "some-user@gmail.com",
"name": "John Doe",
"provider": "google",
"status": "active",
"scopes": [
"https://www.googleapis.com/auth/userinfo.email",
"https://www.googleapis.com/auth/userinfo.profile",
"openid",
"https://www.googleapis.com/auth/calendar.events",
"https://www.googleapis.com/auth/calendar.freebusy",
"https://www.googleapis.com/auth/admin.directory.resource.calendar.readonly",
"https://www.googleapis.com/auth/calendar.calendarlist.readonly",
"https://www.googleapis.com/auth/calendar.calendars.readonly"
]
}
}
}
```
{% endtab %}
{% tab title="400: Bad Request invalid code" %}
```json
{
"success": false,
"error": "invalid_grant", //the code provided is invalid
"code": 400
}
```
{% endtab %}
{% tab title="400: Bad Request no code provided" %}
```json
{
"errors": [
{
"msg": "a code is required.",
"param": "code",
"location": "body"
},
{
"msg": "code must be a string.",
"param": "code",
"location": "body"
}
]
}
```
{% endtab %}
{% endtabs %}
**Note:** Be sure to save the `accountId` returned from the successful connect request. You will need it in order to access the user's Google calendar.
# Calendars
Google Calendars
## Get All Calendars
`GET` `https://api.pyas.io/google/calendars`
Gets all calendars that a user has access to.
#### Query Parameters
| Name | Type | Description |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------------- |
| 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 list of calendars" %}
```json
{
"success": true,
"data": {
"calendars": [
{
"kind": "calendar#calendarListEntry",
"etag": "\"000000000000000000000\"",
"id": "some-user@gmail.com",
"summary": "some-user@gmail.com",
"timeZone": "UTC",
"colorId": "14",
"backgroundColor": "#9fe1e7",
"foregroundColor": "#000000",
"selected": true,
"accessRole": "owner",
"defaultReminders": [
{
"method": "popup",
"minutes": 10
}
],
"notificationSettings": {
"notifications": [
{
"type": "eventCreation",
"method": "email"
},
{
"type": "eventChange",
"method": "email"
},
{
"type": "eventCancellation",
"method": "email"
},
{
"type": "eventResponse",
"method": "email"
}
]
},
"primary": true,
"conferenceProperties": {
"allowedConferenceSolutionTypes": [
"hangoutsMeet"
]
}
},
{
"kind": "calendar#calendarListEntry",
"etag": "\"111111111111111111111111\"",
"id": "en.usa#holiday@group.v.calendar.google.com",
"summary": "Holidays in United States",
"description": "Holidays and Observances in United States",
"timeZone": "UTC",
"colorId": "8",
"backgroundColor": "#16a765",
"foregroundColor": "#000000",
"selected": true,
"accessRole": "reader",
"defaultReminders": [],
"conferenceProperties": {
"allowedConferenceSolutionTypes": [
"hangoutsMeet"
]
}
},
{
"kind": "calendar#calendarListEntry",
"etag": "\"1662297009786000\"",
"id": "addressbook#contacts@group.v.calendar.google.com",
"summary": "Birthdays",
"description": "Displays birthdays, anniversaries, and other event dates of people in Google Contacts.",
"timeZone": "UTC",
"colorId": "13",
"backgroundColor": "#92e1c0",
"foregroundColor": "#000000",
"selected": true,
"accessRole": "reader",
"defaultReminders": [],
"conferenceProperties": {
"allowedConferenceSolutionTypes": [
"hangoutsMeet"
]
}
}
]
}
}
```
{% endtab %}
{% tab title="401: Unauthorized Invalid/missing API key" %}
```json
{
"error": "Unauthorized. Invalid API key."
}
```
{% endtab %}
{% tab title="400: Bad Request Missing account id" %}
```json
{
"errors": [
{
"msg": "an account id is required.",
"param": "accountId",
"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 %}
{% endtabs %}
## Get a Calendar by ID
`GET` `https://api.pyas.io/google/calendars/{id}`
Gets a calendar by id
#### Path Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | ---------------------------------- |
| {id}\* | String | The id of the calendar to retrieve |
#### Query Parameters
| Name | Type | Description |
| ------------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| 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 calendar" %}
```json
{
"success": true,
"calendar": {
"kind": "calendar#calendar",
"etag": "\"000000000000000000\"",
"id": "some-user@gmail.com",
"summary": "some-user@gmail.com",
"timeZone": "UTC",
"conferenceProperties": {
"allowedConferenceSolutionTypes": [
"hangoutsMeet"
]
}
}
}
```
{% 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="401: Unauthorized Invalid/missing API key" %}
```json
{
"error": "Unauthorized. Invalid API key."
}
```
{% endtab %}
{% tab title="400: Bad Request Missing account id" %}
```json
{
"errors": [
{
"msg": "an account id is required.",
"param": "accountId",
"location": "query"
},
{
"msg": "account id must be a string",
"param": "accountId",
"location": "query"
}
]
}
```
{% endtab %}
{% tab title="404: Not Found Calendar Not Found" %}
```json
{
"success": false,
"error": "Not Found",
"code": 404
}
```
{% endtab %}
{% endtabs %}
# 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.
## 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 %}
# Microsoft Outlook
Pyas Microsoft Outlook Integration
Pyas allows developers to connect Microsoft Outlook accounts via OAuth. Developers don't need to worry about handling refresh tokens because we take care of all of that for you.
Developers will be able to read calendars, create, read, update, and delete events.
# Auth
Connect an Outlook Account
There are 2 steps for connecting a Microsoft Outlook account. The first step is to request a Microsoft OAuth URL.
## Get OAuth URL
`GET` `https://api.pyas.io/microsoft/oauth`
#### Query Parameters
| Name | Type | Description |
| --------------------------------------- | ------ | -------------------------- |
| email\* | String | a user's email address |
| state | String | optional application state |
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key\* | String | API key |
{% tabs %}
{% tab title="200: OK OAuth URL was generated successfully" %}
```json
{
"success": true,
"url": "https://login.microsoftonline.com/common/oauth2/v2.0/authorize?client_id=..."
}
```
{% endtab %}
{% tab title="400: Bad Request no email address param was provided" %}
```json
{
"errors": [
{
"msg": "Invalid value",
"param": "email",
"location": "query"
},
{
"msg": "a valid email is required.",
"param": "email",
"location": "query"
}
]
}
```
{% endtab %}
{% tab title="400: Bad Request Invalid email address provided" %}
```json
{
"errors": [
{
"value": "bademail",
"msg": "a valid email is required.",
"param": "email",
"location": "query"
}
]
}
```
{% endtab %}
{% tab title="401: Unauthorized Invalid or no api key provided" %}
```json
{
"error": "Unauthorized. Invalid API key."
}
```
{% endtab %}
{% endtabs %}
## Connect Account
The next step is to connect the account. After you get an OAuth URL, you should direct your user to that URL in the browser. The user will then have to authorized/allow access on the OAuth screen. Once the user allows access, Microsoft will redirect the user back to whatever redirect URL that you've set in Pyas. The URL will contain a `code` parameter, which you will need to use in the connect request.
## Connect Account
`POST` `https://api.pyas.io/microsoft/connect`
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key\* | String | API key |
#### Request Body
| Name | Type | Description |
| -------------------------------------- | ------ | ---------------------------------- |
| code\* | String | code returned from Microsoft OAuth |
| name\* | String | user's full name |
{% tabs %}
{% tab title="200: OK Account connected successfully" %}
```json
{
"success": true,
"data": {
"account": {
"accountId": "03fdd65-d25f-4f00-94e3-9c23ea99738-56321c14",
"email": "example@outlook.com",
"name": "Jon Snow",
"provider": "microsoft",
"status": "active",
"scopes": [
"openid",
"offline_access",
"profile",
"https://graph.microsoft.com/User.Read",
"https://graph.microsoft.com/Calendars.Read",
"https://graph.microsoft.com/Calendars.Read.Shared",
"https://graph.microsoft.com/Calendars.ReadWrite",
"https://graph.microsoft.com/Calendars.ReadWrite.Shared",
]
}
}
}
```
{% endtab %}
{% tab title="400: Bad Request invalid code" %}
```json
{
"success": false,
"error": "invalid_grant",
"code": 400
}
```
{% endtab %}
{% tab title="400: Bad Request no code provided" %}
```json
{
"errors": [
{
"msg": "a code is required.",
"param": "code",
"location": "body"
},
{
"msg": "code must be a string.",
"param": "code",
"location": "body"
}
]
}
```
{% endtab %}
{% endtabs %}
**Note:** Be sure to save the `accountId` returned from the successful connect request. You will need it in order to access the user's Outlook calendar.
# Calendars
Microsoft Outlook Calendars
## Get All Calendars
`GET` `https://api.pyas.io/microsoft/calendars`
Gets all calendars that a user has access to.
#### Query Parameters
| Name | Type | Description |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------------- |
| 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 list of calendars" %}
```json
{
"success": true,
"data": {
"calendars": [
{
"id": "some-calendar-id",
"name": "Calendar",
"color": "auto",
"hexColor": "",
"isDefaultCalendar": true,
"changeKey": "some-key",
"canShare": true,
"canViewPrivateItems": true,
"canEdit": true,
"allowedOnlineMeetingProviders": [
"skypeForConsumer"
],
"defaultOnlineMeetingProvider": "skypeForConsumer",
"isTallyingResponses": true,
"isRemovable": false,
"owner": {
"name": "Jane Doe",
"address": "outlook_some-id@outlook.com"
}
}
]
}
}
```
{% endtab %}
{% tab title="401: Unauthorized Invalid/missing API key" %}
```json
{
"error": "Unauthorized. Invalid API key."
}
```
{% endtab %}
{% tab title="400: Bad Request Missing account id" %}
```json
{
"errors": [
{
"msg": "an account id is required.",
"param": "accountId",
"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 %}
{% endtabs %}
## Get Calendar by ID
`GET` `https://api.pyas.io/microsoft/calendars/{id}`
Gets a calendar by id
#### Path Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | ---------------------------------- |
| {id}\* | String | The id of the calendar to retrieve |
#### Query Parameters
| Name | Type | Description |
| ------------------------------------------- | ------ | -------------------------------------------------------------------------------- |
| 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 calendar" %}
```json
{
"success": true,
"calendar": {
"@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('outlook_some-id@outlook.com')/calendars/$entity",
"id": "some-calendar-id",
"name": "Calendar",
"color": "auto",
"hexColor": "",
"isDefaultCalendar": true,
"changeKey": "some-key",
"canShare": true,
"canViewPrivateItems": true,
"canEdit": true,
"allowedOnlineMeetingProviders": [
"skypeForConsumer"
],
"defaultOnlineMeetingProvider": "skypeForConsumer",
"isTallyingResponses": true,
"isRemovable": false,
"owner": {
"name": "Jane Doe",
"address": "outlook_some-id@outlook.com"
}
}
}
```
{% 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="401: Unauthorized Invalid/missing API key" %}
```json
{
"error": "Unauthorized. Invalid API key."
}
```
{% endtab %}
{% tab title="400: Bad Request Missing account id" %}
```json
{
"errors": [
{
"msg": "an account id is required.",
"param": "accountId",
"location": "query"
},
{
"msg": "account id must be a string",
"param": "accountId",
"location": "query"
}
]
}
```
{% endtab %}
{% tab title="404: Not Found Calendar Not Found" %}
```json
{
"success": false,
"error": "Not Found",
"code": 404
}
```
{% endtab %}
{% endtabs %}
# 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 |
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 |
{% tabs %}
{% tab title="200: OK Successfully retrieved events" %}
```json
{
"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": "\r\n\r\n\r\n\r\n\r\nThis is an appoinemtment test\r\n\r\n\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
}
}
```
{% 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 %}
## 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 |
{% 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/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**](#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.
"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:
```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: "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:
```json
{
"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:
```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:
## Event Data Meta Object Example
More request body fields from the official Microsoft Docs can be found here:
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.
```typescript
{
importance?: string // low, normal, high
isAllDay?: boolean
isCancelled?: boolean
responseRequested?: boolean // true by default
// 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@outlook.com"
}
],
"meta": {
"importance": "high"
}
}
```
### Example EventData with Extended Properties
```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@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 | 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](#event-data-meta-object-example) above. |
{% tabs %}
{% tab title="200: OK Event updated successfully" %}
```json
{
"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": "\r\n\r\n\r\n\r\n\r\nThis is an appoinemtment test\r\n\r\n\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
}
}
```
{% 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/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 |
{% tabs %}
{% tab title="204: No Content Event was deleted successfully" %}
```javascript
{
// Response
}
```
{% endtab %}
{% endtabs %}
# Zoom
Pyas Zoom Integration
Pyas allows developers to connect Zoom accounts via OAuth. Developers don't need to worry about handling refresh tokens because we take care of all of that for you.
Developers will be able to read calendars, create, read, update, and delete Zoom meetings.
# Auth
Connect a Zoom Account
## Get OAuth URL
There are 2 steps for connecting a zoom account. The first step is to request a Zoom OAuth URL.
## Get an OAuth URL
`GET` `https://api.pyas.io/zoom/oauth`
Get a Zoom OAuth URL
#### Query Parameters
| Name | Type | Description |
| ----- | ------ | -------------------------- |
| state | String | optional application state |
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key\* | String | API key |
{% tabs %}
{% tab title="200: OK OAuth URL was generated successfully" %}
```json
{
"success": true,
"url": "https://zoom.us/oauth/authorize?client_id=some-client-id&response_type=code&redirect_uri=some-redirect-url&state=some-state"
}
```
{% endtab %}
{% tab title="401: Unauthorized Invalid or no api key provided" %}
```json
{
"error": "Unauthorized. Invalid API key."
}
```
{% endtab %}
{% endtabs %}
## Connect Account
The next step is to connect the account. After you get an OAuth URL, you should direct your user to that URL in the browser. The user will then have to authorized/allow access on the OAuth screen. Once the user allows access, Zoom will redirect the user back to whatever redirect URL that you've set in Pyas. The URL will contain a `code` parameter, which you will need to use in the connect request.
## Connect Account
`POST` `https://api.pyas.io/zoom/connect`
Connect Zoom Account
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key\* | String | API key |
#### Request Body
| Name | Type | Description |
| -------------------------------------- | ------ | ----------------------------- |
| code\* | String | code returned from Zoom OAuth |
| name\* | String | user's full name |
{% tabs %}
{% tab title="200: OK Account connected successfully" %}
```json
{
"success": true,
"data": {
"account": {
"accountId": "46204525-b574-9ad72ae18c9e-9894161fvsvokok",
"email": "user@example.com",
"name": "John Doe",
"provider": "zoom",
"status": "active",
"scopes": [
"meeting:write",
"user:read",
"user_info:read",
"meeting:read"
]
}
}
}
```
{% endtab %}
{% tab title="400: Bad Request invalid code" %}
```json
{
"success": false,
"error": "Invalid authorization code",
"code": 400
}
```
{% endtab %}
{% tab title="400: Bad Request no code provided" %}
```json
{
"errors": [
{
"msg": "a code is required.",
"param": "code",
"location": "body"
},
{
"msg": "code must be a string.",
"param": "code",
"location": "body"
}
]
}
```
{% endtab %}
{% endtabs %}
**Note:** Be sure to save the `accountId` returned from the successful connect request. You will need it in order to access the user's Zoom account.
# Meetings
Zoom Meetings
## Get All Meetings
## Get List of Meetings
`GET` `https://api.pyas.io/zoom/meetings`
Gets all meetings for an account
#### Query Parameters
| Name | Type | Description |
| ------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| accountId\* | String | The user's Pyas account id. This is returned when you connect an account to Pyas. |
| startDate | Date String |
Filter meetings from a start date
(ex: 01-01-2022)
|
| endDate | Date String |
Filter meetings up to an end date
(ex: 01-01-2023)
|
| nextPageToken | String | Token string used to get the next page of results (paginate) - This token expires after 15 minutes |
| maxResults | Integer | Max number of results to return per page |
| type | String |
Type of meeting. Possible values are: scheduled - All valid previous (unexpired) meetings, live meetings, and upcoming scheduled meetings.
live - All the ongoing meetings.
upcoming - All upcoming meetings, including live meetings.
upcoming\_meetings - All upcoming meetings, including live meetings.
previous\_meetings - All the previous meetings.
|
| pageNumber | Integer | The page number of the current page in the returned records. |
#### Headers
| Name | Type | Description |
| ------------------------------------------- | ------ | ----------- |
| x-api-key\* | String | API key |
{% tabs %}
{% tab title="200: OK Successfully retrieved meetings" %}
```json
{
"success": true,
"data": {
"page_size": 30,
"total_records": 1,
"next_page_token": "",
"meetings": [
{
"uuid": "some-uuid-string",
"id": 3418139842191568,
"host_id": "some-id-string",
"topic": "Test Meeting",
"type": 2,
"start_time": "2023-04-26T19:26:55Z",
"duration": 30,
"timezone": "America/Los_Angeles",
"agenda": "This is an example meeting",
"created_at": "2023-04-26T12:26:57Z",
"join_url": "https://us05web.zoom.us/j/81398421915?pwd=Zk9WTzM3SG9Xb1lCZk9MTVFhOU1Fdz09"
}
]
}
}
```
{% 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 %}
## Get an Event By ID
## Get Event by ID
`GET` `https://api.pyas.io/zoom/meetings/:id`
Gets a calendar event by id
#### Path Parameters
| Name | Type | Description |
| -------------------------------------- | ------ | -------------- |
| {id}\* | String | The meeting id |
#### Query Parameters
| Name | Type | Description |
| ------------------------------------------- | ------ | --------------------------------------------------------------------------------- |
| 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 meeting" %}
```json
{
"success": true,
"meeting": {
"uuid": "some-uuid-string",
"id": 181328421905,
"host_id": "some-id-string",
"host_email": "user@example.com",
"assistant_id": "",
"topic": "Test Meeting",
"type": 2,
"status": "waiting",
"start_time": "2023-04-26T19:26:55Z",
"duration": 30,
"timezone": "America/Los_Angeles",
"agenda": "This is an example meeting",
"created_at": "2023-04-26T12:26:57Z",
"start_url": "https://us05web.zoom.us/s/8139...",
"join_url": "https://us05web.zoom.us/j/81398...",
"password": "f0a9n07bk3",
"h323_password": "7214044450",
"pstn_password": "7214044450",
"encrypted_password": "Zk9WTzM3SG9Xb1lCZk9MTVFhOU1Fdz09",
"settings": {
"host_video": false,
"participant_video": false,
"cn_meeting": false,
"in_meeting": false,
"join_before_host": false,
"jbh_time": 0,
"mute_upon_entry": false,
"watermark": false,
"use_pmi": false,
"approval_type": 2,
"audio": "voip",
"auto_recording": "none",
"enforce_login": false,
"enforce_login_domains": "",
"alternative_hosts": "",
"alternative_host_update_polls": false,
"close_registration": false,
"show_share_button": false,
"allow_multiple_devices": false,
"registrants_confirmation_email": true,
"waiting_room": true,
"request_permission_to_unmute_participants": false,
"registrants_email_notification": true,
"meeting_authentication": false,
"encryption_type": "enhanced_encryption",
"approved_or_denied_countries_or_regions": {
"enable": false
},
"breakout_room": {
"enable": false
},
"alternative_hosts_email_notification": true,
"show_join_info": false,
"device_testing": false,
"focus_mode": false,
"enable_dedicated_group_chat": false,
"private_meeting": false,
"email_notification": true,
"host_save_video_order": false
},
"pre_schedule": false
}
}
```
{% 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": "account id is required",
"param": "accountId",
"location": "query"
},
{
"msg": "account id must be a string",
"param": "accountId",
"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 %}
{% endtabs %}
##
## Create a Meeting
## Create Meeting
`POST` `https://api.pyas.io/zoom/meetings`
Creates a new Zoom Meeting
#### 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. |
| meetingData\* | Object | The event data. See the Required [**Meeting Data Object**](#meeting-data-object) example below. |
| meetingData.title\* | String | The meeting title/topic |
| meetingData.description\* | String | Meeting description/agenda |
| meetingData.startDate\* | DateTime | RFC3339 Timestamp |
| meetingData.timeZone | String | Time Zone in IANA format. Only used for scheduled or recurring meetings with a fixed time |
| meetingData.attendees | Array | Array of [**Attendee Objects**](#attendee-object-example) |
| meetingData.recurrence | Object | Recurrence object for recurring events. See the [**Recurrence Object**](#recurrence-object) below. |
| meetingData.duration | Integer | The meeting duration in minutes. Only used for scheduled meetings. Defaults to **30** |
| meetingData.waitingRoom | Boolean | Whether to enable or disable the waiting room |
| meetingData.type\* | Integer |
Type of meeting:
1 - An instant meeting
2 - A scheduled meeting
3 - A recurring meeting with no fixed time
8 - A recurring meeting with fixed time
|
{% tabs %}
{% tab title="200: OK Meeting created successfully" %}
```json
{
"success": true,
"data": {
"uuid": "some-uuid-string",
"id": 2589906727501,
"host_id": "some-id-string",
"host_email": "email@example.com",
"topic": "Test Meeting",
"type": 2,
"status": "waiting",
"start_time": "2023-04-26T19:51:48Z",
"duration": 30,
"timezone": "America/Los_Angeles",
"agenda": "This is an example meeting",
"created_at": "2023-04-26T12:51:49Z",
"start_url": "https://us05web.zoom.us/s/85256...",
"join_url": "https://us05web.zoom.us/j/8965...",
"password": "aeknj5fia0",
"h323_password": "4023135285",
"pstn_password": "4023135285",
"encrypted_password": "YmJva3V5TlpZMDQ1SzJZOUNCemUrQT09",
"settings": {
"host_video": false,
"participant_video": false,
"cn_meeting": false,
"in_meeting": false,
"join_before_host": false,
"jbh_time": 0,
"mute_upon_entry": false,
"watermark": false,
"use_pmi": false,
"approval_type": 2,
"audio": "voip",
"auto_recording": "none",
"enforce_login": false,
"enforce_login_domains": "",
"alternative_hosts": "",
"alternative_host_update_polls": false,
"close_registration": false,
"show_share_button": false,
"allow_multiple_devices": false,
"registrants_confirmation_email": true,
"waiting_room": true,
"request_permission_to_unmute_participants": false,
"registrants_email_notification": true,
"meeting_authentication": false,
"encryption_type": "enhanced_encryption",
"approved_or_denied_countries_or_regions": {
"enable": false
},
"breakout_room": {
"enable": false
},
"alternative_hosts_email_notification": true,
"show_join_info": false,
"device_testing": false,
"focus_mode": false,
"enable_dedicated_group_chat": false,
"private_meeting": false,
"email_notification": true,
"host_save_video_order": false
},
"pre_schedule": false
}
}
```
{% 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="400: Bad Request Missing required fields" %}
```json
{
"errors": [
{
"msg": "meetingData is required.",
"param": "meetingData",
"location": "body"
},
{
"msg": "meetingData must be an object",
"param": "meetingData",
"location": "body"
},
{
"msg": "Invalid value",
"param": "meetingData",
"location": "body"
}
]
}
```
{% endtab %}
{% endtabs %}
### **Meeting Data Object**
```json
{
"accountId": "123654-46204525-b574-9ad72ae18c9e", // string - Required.
"meetingData": {
"type": 2, // Integer - Required.
"title": "Test Meeting", // string - Required.
"description": "This is an example meeting", // string - Required.
"startDate": "{{start_time}}", // RFC3339 Timestamp - Required.
"duration": 30, // Integer - Required.
"waitingRoom": true, // Boolean - Optional.
"attendees": [
{
"email": "example@gmail.com"
}
] // Required.
}
}
```
### Attendee Object Example:
```json
{
"email": "example@gmail.com" // String - Required.
}
```
### 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: