How can events be evenly distributed across multiple recipients?

When making Availability Queries to create events for a team of people, it can be common to want to assign those events evenly.

For example, if Alice and Bob are being chosen to hold interviews and Alice has 3 more booked than Bob, we might want to make Bob more likely to be chosen. However, we don’t want to remove Alice from the Availability Query until Bob catches up, in case Alice can offer a time that Bob is not available. We still want to fall back to Alice if Bob isn’t available.

There are two potential solutions to this issue:

As participants are processed in the order they are provided in. Participants at the start of the list are preferred over participants further down the list.

This gives you a degree of control over who is more likely to be picked. Shuffling the order of the participants so that each Availability Query provides a different list is an excellent way to approximate an even distribution of events.

Another way to achieve this through non-API means is to set up tracking on the receivers’ side. Sorting the participants by ’least events booked’ to ‘most’ will more actively increase the chances of fair event distribution, allowing you to control the window you are considering.

To achieve this, the amount of available time each of the event receivers has needs to be measured and received. This is so that those with the largest amount of available free time, represented in open blocks on the scheduler, can be assigned events first.

In this example, we are imagining we have Alice and Bob taking interviews again.

Alice has 5 interviews booked this week. Her account is acc_64b17d868090ea21640c914c. Bob has 2 interviews booked this week. His account is acc_5ba21743f408617d1269ea1e.

To make Bob more likely to be booked, we put him first in our query:

Example Request #

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", // first in the list so will be preferred
          "calendar_ids": ["cal_n23kjnwrw2_jsdfjksn234"]
        },
        {
          "sub": "acc_64b17d868090ea21640c914c" // second in order, so still offering time but only when participants higher in the queue are not available
        }
      ],
      "required": "all"
    }
}