How to sync Google and Outlook Calendars via the API

Calendar Syncing with Google and Outlook

Relevant Endpoints include:

POST/setup/v1/resources
PUT/setup/v1/resources/{id}
PUT/setup/v1/resources/bulk
GET/setup/v1/resources/{id}/calendar/auth/google/{googleEmailAddress}
GET/setup/v1/resources/{id}/calendar/auth/outlook/{outlookEmailAddress}

Creating a resource with Google or Outlook calendar integration via the API

This section discusses how calendar appointment posting and availability for Google & Outlook calendars gets set up and functions.

POST/setup/v1/resources

Setting up external calendar integration can be done when you first create a resource or later if necessary. There are four pieces to a successful integration.

1.  The Google or Outlook username
2. The return URL, which tells the system where to redirect the resource to after the calendar has been authorized.
3. The authorization of the external calendar. This authorization allows OnSched to post appointments to the resources external calendar.
4. If you would like to use the external calendar during the availability calculation, you must define which external calendar you want us to access when determining your availability. You may set Google: 1, Outlook: 2 or None: 0 for calendarAvailability.

Relevant Fields and Definitions

In the query parameters of the POST Resource endpoint you need include either googleAuthReturnUrl or outlookAuthReturnUrl.  Enter the appropriate Url of the page that you want to redirect the resource back to, after they have successfully authorized their calendar.

In the body of the post resource body, you will find the calendar sync related fields in the “options” section.

"options": {
  ...
  "googleCalendarId": "string",
  "outlookCalendarId": "string",
  "calendarAvailability": 0,
  ...
},

"googleCalendarId": The “Google email address” of the resources calendar you want to integrate with

To connect to a Google Calendar you must use a Google email address, this may be an @gmail or @company email address as long as it is hosted by Gmail.  To connect the account, enter the Google email address as the googleCalendarId, then save the resource.  The response will contain a googleCalendarAuthUrl, which you may provide to the resource.  When they paste this link into their browser and navigate to the page, Google will ask them to authorize their calendar for use by OnSched.  Once authorized, OnSched will be able to access the resource's Google calendar.

"outlookCalendarId": The “Outlook email address” of the resources calendar you want to integrate with

To connect to an Outlook Calendar you must use an Outlook email address, this may be an @outlook, @hotmail, @live, or @company email address as long as it is hosted by Microsoft. To connect the account, enter the Outlook email address as the outlookCalendarId, then save the resource.  The response will contain a outlookCalendarAuthUrl, which you may provide to the resource.  When they paste this link into their browser and navigate to the page, Outlook will ask them to authorize their calendar for use by OnSched.  Once authorized, OnSched will be able to access the resource's Outlook calendar.

Note: You cannot sync to both google and outlook calendars, only one.

"calendarAvailability": This field determines how OnSched will calculate a resources availability. Valid options are 0, 1 or 2

The calendarAvailability field is the setting to define which calendar you want OnSched to access when determining the resources availability.

0 = OnSched Calendar - Passing in a “0” will look at the OnSched calendar to determine availability for that resource. This will ignore any appointments from external calendars.

1 = Google Calendar - Passing in a “1” will look at the resources Google calendar as well as OnSched availability information when determining availability.

2 = Outlook Calendar - Passing in a “2” will look at the resources Outlook calendar as well as OnSched availability information when determining availability.

These fields in conjunction with a SUCCESSFUL OUTLOOK or GOOGLE AUTHORIZATION will result in the following functionality.

All appointments will automatically be posted to your OnSched Calendar.

If either of the GoogleID or OutlookID are populated with valid email addresses, and the calendars were authorized, we will also post appointments to that calendar also.

Note:  If calendars are not properly authorized only the OnSched calendar will be used in all cases.

STEPS TO SET UP AN EXTERNAL CALENDAR via API

Instructions provided here detail how to set up External calendar integration via the POST RESOURCES endpoint.  A similar approach works using the PUT RESOURCES endpoint if you need to do it after the resource has been created.

To set up the calendar syncing you need to pass in a Google or Outlook return URL, along with either a Google or Outlook calendar id and the calendarAvailability parameter as defined above.

STEP 1 - Enter the return URL in either the googleAuthReturnUrl or outlookAuthReturnUrl query parameter (e.g. /setup/v1/resources?googleAuthUrl=https://example.com/profile). This is the url that the resource will be returned to after they have completed the authorization process.

STEP 2 - Here is an example of the Post Resource body needed to set up an external calendar. Add the following items to the POST Resource Body when setting up a Google Calendar integration.

{
  "name": "Resource Name",
  "email": "resource@gmail.com",
  "options": {
    "googleCalendarId": "resource@gmail.com",
    "calendarAvailability": 1,
  }
}

This will create a resource who is set up for Google integration. The next step is to authorize. In the POST response you will see the Google Calendar Authorization URL labelled “googleCalendarAuthUrl”.

STEP 3 - The AUTHORIZATION URL looks something like this.

"googleCalendarAuthUrl": "https://accounts.google.com/o/oauth2/auth?client_id=578520729152-544te8112lvhi48uq7h2q0abies78qvr.apps.googleusercontent.com&redirect_uri=https://app.onsched.com/app/GoogleCallback.aspx&scope=https://www.googleapis.com/auth/calendar&response_type=code&state=resourceId=38335;returnUrl=https://example.com/profile&access_type=offline&approval_prompt=force&login_hint=resource@gmail.com"

STEP 4 - Copy the authorization URL and paste it into your browser to launch Google Authorization.

STEP 5 - Once the resource has authorized, they will be redirected to the googleAuthReturnUrl or the outlookAuthReturnUrl supplied in the original POST call.

Note: When and where in your process you authorize the resources external calendar is dependent on your resource onboarding workflow. Once the resource is set up, you can access the authorization url anytime by using the appropriate endpoint:

GET/setup/v1/resources/{id}/calendar/auth/google/{googleEmailAddress}

GET/setup/v1/resources/{id}/calendar/auth/outlook/{outlookEmailAddress}