Personalized availability preferences with the Availability API

How the Availability API can be queried with respect to participant availability and working hours preferences.

The type of meeting or event your application is creating can have an impact on the when the participant would consider themselves available. For example interviews may only be conducted on Monday, Tuesdays and Thursdays between 10am and 1pm by some of the interview panel.

In this simple example of an Availability query, global working hours are described in the available_periods element.

{
  "participants": [
    {
      "members": [
        {
          "sub": "acc_567236000909002"
        },
        {
          "sub": "acc_678347111010113"
        }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 60 },
  "available_periods": [
    {
      "start": "2017-07-17T09:00:00Z",
      "end": "2017-07-17T18:00:00Z"
    },
    {
      "start": "2017-07-18T09:00:00Z",
      "end": "2017-07-18T18:00:00Z"
    }
  ]
}

Which works well when you're looking at a working day or there are global rules about when something can be scheduled.

The Availability API also supports specifying available_periods at a member level. So if you know that the first participant only interviews on Mondays and Tuesdays between 10am and 1pm UTC you would add that to the appropriate member element as shown.

{
  "participants": [
    {
      "members": [
        {
          "sub": "acc_567236000909002",
          "available_periods": [
            {
              "start": "2017-07-17T10:00:00Z",
              "end": "2017-07-17T13:00:00Z"
            },  
            {
              "start": "2017-07-18T10:00:00Z",
              "end": "2017-07-18T13:00:00Z"
            }
          ]          
        },
        {
          "sub": "acc_678347111010113"
        }
      ],
      "required": "all"
    }
  ],
  "required_duration": { "minutes": 60 },
  "available_periods": [
    {
      "start": "2017-07-17T09:00:00Z",
      "end": "2017-07-17T18:00:00Z"
    },
    {
      "start": "2017-07-18T09:00:00Z",
      "end": "2017-07-18T18:00:00Z"
    }
  ]
}

This is then used as part of the availability query. So this provides a really simple way of your application leveraging the power of the Availability API and respecting their working preferences.