Buffers

Buffers are used to filter available times to ensure a given duration is free before and/or after an event.

Buffer times do not form part of the event, so the duration of the event is unaffected by the buffer duration.

An example: Scheduling an interview #

An interviewer might need 30 minutes free before the interview to review the candidates CV and questions. They then need 30 minutes free after the interview to write up notes.

If we add this extra time to the event then the candidate would turn up too early.

If we create separate events for the candidate and interviewer with different lengths, the interview might not realize and think the candidate has turned up late.

Buffers solve this problem. We create a single interview event and schedule it with enough time around it for the interviewers extra activities.

Buffers are only considered while calculating availability or scheduling an event; Buffer times are not kept free after the event is created. After scheduling our event with buffers, another event could be created within the buffer periods. For some examples and patterns to deal with these situations, see the Helpful Patterns below.

To find a time to hold our interview, we could make the following request to the Availability API:

POST /v1/availability HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8

{
  "participants":[{
      "members":[
        { "sub": "acc_5ba21743f408617d1269ea1e" },
        { "sub": "acc_64b17d868090ea21640c914c" }
      ],
      "required":"all"
  }],
  "required_duration": { "minutes": 60 },
  "query_periods": [
    {
      "start": "2024-07-27T09:00:00Z",
      "end": "2024-07-27T18:00:00Z"
    },
    {
      "start": "2024-07-28T09:00:00Z",
      "end": "2024-07-28T18:00:00Z"
    }
  ],
  "buffer": {
    "before": { "minutes": 30 },
    "after": { "minutes": 30 }
  }
}

This will search for spaces in the calendar that are 90 minutes long:

• 30 minutes for the before buffer (from buffer.before)
• 30 minutes for the event duration (from the required_duration)
• 30 minutes for the after buffer (from buffer.after)

A candidate window of time could be visualised like this:

Even though the slot from 9:30 - 10:00 is free and the right duration for the event, it is not long enough for our new event including the buffers and is discarded.

The gap from 10:30 - 12:00 is wide enough to accommodate the event and buffers, and is considered.

Helpful Patterns #

Keeping buffer times reserved #

Buffers are considered when calculating availability and scheduling events but do not offer any “protection” of the before/after time once the event has been created. However, we may want that time to be held for a reason.

Returning to the earlier example of scheduling an interview with preparation time before and note making time afterwards,these buffer times represent activities that should used for specific reasons.

This can be solved with the following pattern:

1. Use one of the scheduling APIs (such as the Availability API ) to find a time for the main interview event with buffers set to account for the interviewers tasks either side
2. Create events in the before and after buffers to describe what the time is held for.

This pattern prevents double-booking thanks to the extra events, and helps the end user know that there is time set aside for specific reason. In the interview example, we would create an event before the interview called “Read candidates CV” and an event after the interview called “Write up interview notes and feedback”

Using buffers with Sequenced Availability #

Buffers can be used during sequencing to separate events. There is more information available on the Sequenced Availability page about this.

Different buffers for participants in an Availability query #

Sometimes you need an exception to the event-level buffers and want to have one or more participants considered differently.

An example would be searching for a time for a speaker to talk to a small group. A before buffer of 10 minutes gives the attendees enough time to find the room and take their seats. The speaker needs more time to set up the projector and check their slides, so we want to give them a before buffer of 20 minutes.

The Availability API enables this using the Participant buffers option.

Our availability query would look like this:

POST /v1/availability HTTP/1.1
Host: {data_center_url}
Authorization: Bearer {API_KEY}
Content-Type: application/json; charset=utf-8

{
  "participants":[{
      "members":[
        {
          "sub": "acc_5ba21743f408617d1269ea1e",
          "buffer": {
            "before": { "minutes": 20 },
          }
        },
        { "sub": "acc_64b17d868090ea21640c914c" },
        { "sub": "acc_64b186438090ea21640c9160" },
        { "sub": "acc_64b545fd18d61c8fd50583a1" },
        { "sub": "acc_64b5487b18d61c8fd50583a4" }
      ],
      "required":"all"
  }],
  "required_duration": { "minutes": 60 },
  "available_periods": [
    {
      "start": "2024-07-27T09:00:00Z",
      "end": "2024-07-27T18:00:00Z"
    },
    {
      "start": "2024-07-28T09:00:00Z",
      "end": "2024-07-28T18:00:00Z"
    }
  ],
  "buffer": {
    "before": { "minutes": 10 },
  }
}

Our speaker, represented by the first object in the participants.members list, is given a personal before buffer of 20 minutes. The other participants availability is considered using the events buffer of 10 minutes.

The query will only return possible times where the speaker is free for 20 minutes before and the other attendees are free 10 minutes before.

Personalized buffers can be set for as many participants as needed.