Ignoring Calendar Events

There are situations where it makes sense to ignore the events in someone’s calendars when generating a list of availabile slots using the Availability API.

A few examples of when this may be needed includes:

• A recruiter has pre-agreed solts to offer a candidate with a hiring manager
• A Sales Person needs to fit a call in with a client and is happy to override internal meetings
• A work conference marks out the team as busy for external calls but wants to be availble for in person meetings

In these situations you may still want to respect someone’s working hours as defined with Availability Rules or Availability Periods, or you may want to provide times outside of their working hours. Either way, it is possible to ignore events already booked into someone’s calendar.

How to Ignore Events #

There are a few different ways to ignore a persons events, some will ignore all events present in the calendar, whereas others will ignore a specific type of event from the Availability query.

Ignore all events #

The participants.members.calendar_ids parameter restricts the events contributing towards the members availability to those within the set of specified calendar_ids.

If this is passed as an empty array to the in the Availability query then all events in the participants calendars are ignored.

{
  "participants": [
    {
      "members": [
        {
          "sub": "acc_64b17d868090ea21640c914c",
          "calendar_ids": [],
          "managed_availability": true
        }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 30 },
  "query_periods": [
    {
      "start": "2024-07-28T00:00:00Z",
      "end": "2024-07-29T00:00:00Z"
    }
  ]
}

The above query we’re generating slots for 2024-07-28 and respecting the Availability Rules for the participant with sub value of acc_64b17d868090ea21640c914c.

Ignore Unmanaged Events #

If you wish to ignore events that your application isn’t managing, the participants.members.only_managed_events boolean - if set to true - only consider events that you are managing when determining busy times for this member. This defaults to false if not specified.

A managed event means an event that has been created by your application.

{
  "participants": [
    {
      "members": [
        {
          "sub": "acc_64b17d868090ea21640c914c",
          "calendar_ids": ["cal_n23kjnwrw2_jsdfjksn234"],
          "managed_availability": true,
          "only_managed_events": true
        }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 30 },
  "query_periods": [
    {
      "start": "2024-07-28T00:00:00Z",
      "end": "2024-07-29T00:00:00Z"
    }
  ]
}

In this example we have set the query to only consider managed events in the availability query and to ignore any other events for the participant with sub value of acc_64b17d868090ea21640c914c and calendar_ids of cal_n23kjnwrw2_jsdfjksn234.

Ignore Tentative Events #

If you wish to ignore events the participant has marked as “tentative” in the availability query then the participants.members.ignore_tentative boolean - if set to true - will consider events marked as tentatively attending as free periods. This defaults to false if not specified and will consider these event as busy periods.

{
  "participants": [
    {
      "members": [
        {
          "sub": "acc_64b17d868090ea21640c914c",
          "calendar_ids": ["cal_n23kjnwrw2_jsdfjksn234"],
          "ignore_tentative": true
        }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 30 },
  "query_periods": [
    {
      "start": "2024-07-28T00:00:00Z",
      "end": "2024-07-29T00:00:00Z"
    }
  ]
}

In this example we have set the query to ignore any events in the participants calendar that have been marked at tentative in the availability query.

Ignore all events including Availability Rules #

You might want to ignore not only the events in a users calendar, but also the managed availabilty rules so that the query can offer time outside of their normal working hours.

In this example instead of using Availability Rules we’re manually setting the periods that the participant is available for.

{
  "participants": [
    {
      "members": [
        {
          "sub": "acc_64b17d868090ea21640c914c",
          "calendar_ids": [],
          "available_periods": [
            {
              "start": "2024-07-28T09:00:00Z",
              "end": "2024-07-28T12:00:00Z"
            },
            {
              "start": "2024-07-28T16:00:00Z",
              "end": "2024-07-28T17:00:00Z"
            }
          ]
        }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 30 },
  "query_periods": [
    {
      "start": "2024-07-28T09:00:00Z",
      "end": "2024-07-28T18:00:00Z"
    }
  ]
}