Constraints

Required plan: Emerging

Constraints allow additional requirements to be checked when considering a participant.

Limiting a participant to a maximum number of events with a particular tag is currently supported, allowing for Availability to consider a constraint such as “The participant should not be available is they already have 3 screening interviews that week”

An example: Scheduling many interviews #

When scheduling interviews, you may have multiple potential interviewers who are able to meet with a potential candidate. These interviews are 30 minutes long, and each interviewer should only be doing a maximum of 3 interviews in a week period so that they are able to maintain enough free time to meet their regular duties and the time offered for each individual is limited.

Without constraints and when an interviewer has a free week its possible that they will end up with the bulk of the interviews scheduled against them, exceeding the maximum of 3 interviews per week they should be conducting.

Constraints have been added to solve this problem, and work in conjunction with tags to mark events as being of a specific event type. In this example we have marked our interview events as having the tag “Interview” which is used by the availability constraint to limit the number of interview events for each participant per week.

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_567236000909002",
          "availability_constraints":[{
            "tags": { 
              "private": [ 
                { "value": "Interview" }
              ]
            },
            "limit": 3,
            "period": "week"
          }]
        },
        { 
          "sub": "acc_599014084108223",
          "availability_constraints":[{
            "tags": { 
              "private": [ 
                { "value": "Interview" }
              ]
            },
            "limit": 3,
            "period": "week"
          }]
        }
      ],
      "required": 1
  }],
  "required_duration": { "minutes": 30 },
  "query_periods": [
    {
      "start": "2023-02-08T09:00:00Z",
      "end": "2023-02-08T18:00:00Z"
    },
    {
      "start": "2023-02-09T09:00:00Z",
      "end": "2023-02-09T18:00:00Z"
    }
  ]
}

Helpful Patterns #

Using constraints with Sequenced Availability #

Availability constraints can be used during sequencing with the possibility of specifying unique constraints per member per slot. There is more information available on the Sequenced Availability page about this.

Different constraints for participants in an Availability query #

Sometimes you may need different constraints per participant when searching for an available period.

An example of this would be that you may have multiple interviewers present, one member of HR which conducts interviews across departments, and one department head who should keep to the 3 interviews per week limit.

This is possible by specifying differing availability constraints per participant:

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_567236000909002",
          "availability_constraints":[{
            "tags": { 
              "private": [ 
                { "value": "Interview" }
              ]
            },
            "limit": 10,
            "period": "week"
          }]
        },
        { 
          "sub": "acc_599014084108223",
          "availability_constraints":[{
            "tags": { 
              "private": [ 
                { "value": "Interview" }
              ]
            },
            "limit": 3,
            "period": "week"
          }]
        }
      ],
      "required":"all"
  }],
  "required_duration": { "minutes": 30 },
  "query_periods": [
    {
      "start": "2023-02-08T09:00:00Z",
      "end": "2023-02-08T18:00:00Z"
    },
    {
      "start": "2023-02-09T09:00:00Z",
      "end": "2023-02-09T18:00:00Z"
    }
  ]
}

In this example our member of HR is represented by the first member in the participant group with a limit of 10 events with the tag “Interview” per week. The other participant is our department head and can only do 3 “Interview” tagged events per week.