Constraints

Required plan: Emerging

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

Limiting a participant to either a maximum overall number of events, or to a maximum number of events with a particular set of tags is currently supported. This allows for Availability to consider constraints such as:

  • The participant should not be available if they already have 3 screening interviews that week
  • The participant should not be available if they already have 10 events that day

It is also possible to combine multiple constraints to achieve more complex scheduling rules.

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_5ba21743f408617d1269ea1e",
          "availability_constraints":[{
            "tags": {
              "private": [
                { "value": "Interview" }
              ]
            },
            "limit": 3,
            "period": "week"
          }]
        },
        {
          "sub": "acc_64b17d868090ea21640c914c",
          "availability_constraints":[{
            "tags": {
              "private": [
                { "value": "Interview" }
              ]
            },
            "limit": 3,
            "period": "week"
          }]
        }
      ],
      "required": 1
  }],
  "required_duration": { "minutes": 30 },
  "query_periods": [
    {
      "start": "2024-12-19T09:00:00Z",
      "end": "2024-12-19T18:00:00Z"
    },
    {
      "start": "2024-12-20T09:00:00Z",
      "end": "2024-12-20T18: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.

Limiting to a maximum number of events per day #

You may want to limit a participant to a maximum number of events per day, regardless of the tags on those events. To achieve this you can omit the tags field of the constraint, set it to null, the empty object {}, or leave the context as an empty array { "private": [] }.

An example of where you would want to do this is for an technical interview that would require a specialist as well as a member of HR. In this case the specialist is limited to 2 events total per day so they can focus on their day to day work, and the HR team member is limited to 5 interviews per week.

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",
          "availability_constraints":[{
            "limit": 2,
            "period": "day",
            "tzid": "Europe/London"
          }]
        },
        {
          "sub": "acc_64b17d868090ea21640c914c",
          "availability_constraints":[{
            "tags": {
              "private": [
                { "value": "Interview" }
              ]
            },
            "limit": 5,
            "period": "week"
          }]
        }
      ],
      "required":"all"
  }],
  "required_duration": { "minutes": 30 },
  "query_periods": [
    {
      "start": "2024-12-19T09:00:00Z",
      "end": "2024-12-19T18:00:00Z"
    }
  ]
}

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_5ba21743f408617d1269ea1e",
          "availability_constraints":[{
            "tags": {
              "private": [
                { "value": "Interview" }
              ]
            },
            "limit": 10,
            "period": "week"
          }]
        },
        {
          "sub": "acc_64b17d868090ea21640c914c",
          "availability_constraints":[{
            "tags": {
              "private": [
                { "value": "Interview" }
              ]
            },
            "limit": 3,
            "period": "week"
          }]
        }
      ],
      "required":"all"
  }],
  "required_duration": { "minutes": 30 },
  "query_periods": [
    {
      "start": "2024-12-19T09:00:00Z",
      "end": "2024-12-19T18:00:00Z"
    },
    {
      "start": "2024-12-20T09:00:00Z",
      "end": "2024-12-20T18: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.

Combining multiple constraint periods #

To achieve complex scheduling rules you may find it useful to combine multiple constraint periods, sometimes even to the same participant.

An example of when this may be required is if you have an interviewer who can be scheduled for a maximum of 2 interviews per day, but only to a total of 5 interviews per week.

This is possible by specifying multiple availability constraints for the same participant.

For example, to schedule up to 2 interviews a day, with up to 5 total that week, the following query can be made:

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",
          "availability_constraints": [
            {
              "tags": {
                "private": [
                  { "value": "Interview" }
                ]
              },
              "limit": 2,
              "period": "day",
              "tzid": "Europe/London"
            },
            {
              "tags": {
                "private": [
                  { "value": "Interview" }
                ]
              },
              "limit": 5,
              "period": "week"
            }
          ]
        }
      ],
      "required": "all"
  }],
  "required_duration": { "minutes": 30 },
  "query_periods": [
    {
      "start": "2024-12-19T09:00:00Z",
      "end": "2024-12-26T18:00:00Z"
    }
  ]
}