Version:
Only show these results:

Calendar cookbook

Managing availability to schedule events is one of the most common calendar activities. The following sections show examples of different types of Nylas v2 requests, and their responses.

Feature support

Endpoint Scopes Provider Availability SDK Support Feature Availability
Availability calendar
calendar.read_only		 Microsoft
Google		 Python - Open Hours is not supported. Availability does support Room Resources. Just treat it as an email address when checking availability.
Consecutive Availability calendar
calendar.read_only		 Microsoft
Google		 None Consecutive Availability does support Room Resources. Just treat it as an email address when checking availability.
Free/Busy calendar
calendar.read_only		 Microsoft
Google		 Python
Java
Node		 Free/Busy does not support Virtual Calendars.

Free/Busy does not support Room Resources.

Basic availability example request and response

The example below shows the JSON for a basic Availability endpoint request. When you make your POST request, the endpoint returns availability information.

{
  "duration_minutes": 30,
  "start_time": 1605794400,
  "end_time": 1605826800,
  "interval_minutes": 10,
  "emails": [
    "jane.doe@example.com"
  ],
  "free_busy": [{
    "email": "lamarr@example.com",
    "object": "free/busy",
    "time_slots": [{
      "start_time": 1601042400,
      "end_time": 1601044200,
      "object": "time_slot",
      "status": "busy"
    }]
  }],
  "open_hours": [{
    "emails": [
      "jane.doe@example.com"
    ],
    "days": [
      "0"
    ],
    "timezone": "America/Chicago",
    "start": "10:00",
    "end": "14:00",
    "object_type": "open_hours"
  }]
}   
{
  "object": "availability",
  "time_slots": [
    {
      "end": 1605803400,
      "object": "time_slot",
      "start": 1605801600,
      "status": "free"
    },
    {
      "end": 1605804000,
      "object": "time_slot",
      "start": 1605802200,
      "status": "free"
    },
    {
      "end": 1605804600,
      "object": "time_slot",
      "start": 1605802800,
      "status": "free"
    },
    {
      "end": 1605805200,
      "object": "time_slot",
      "start": 1605803400,
      "status": "free"
    },
    {
      "end": 1605805800,
      "object": "time_slot",
      "start": 1605804000,
      "status": "free"
    },
    {
      "end": 1605806400,
      "object": "time_slot",
      "start": 1605804600,
      "status": "free"
    },
    {
      "end": 1605807000,
      "object": "time_slot",
      "start": 1605805200,
      "status": "free"
    },
    {
      "end": 1605816000,
      "object": "time_slot",
      "start": 1605814200,
      "status": "free"
    }
  ]
}

Learn More

Review the Availability APIs.

Check collective availability with Free/Busy

This option uses free_busy object information.

curl --location --request POST 'https://api.nylas.com/calendars/availability' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --data-raw '{
    "duration_minutes": 15,
    "start_time": 1647889200,
    "end_time": 1647900000,
    "interval_minutes": 5,
    "emails": [
      "marie@example.com",
      "ada@example.com",
      "dorothy@example.com"
    ],
    "free_busy": [
      {
        "email": "marie@example.com",
        "object": "free_busy",
        "time_slots": [
          {
            "start_time": 1647889200,
            "end_time": 1647896400,
            "object": "time_slot",
            "status": "busy"
          }
        ]
      },
      {
        "email": "ada@example.com",
        "object": "free_busy",
        "time_slots": [{
          "start_time": 1647889200,
          "end_time": 1647896400,
          "object": "time_slot",
          "status": "busy"
        }]
      },
      {
        "email": "dorothy@example.com",
        "object": "free_busy",
        "time_slots": [{
          "start_time": 1647889200,
          "end_time": 1647896400,
          "object": "time_slot",
          "status": "busy"
        }]
      }
    ]
  }'   
{
  "object": "availability",
  "time_slots": [
    {
      "end": 1647897300,
      "end_time": 1647897300,
      "object": "time_slot",
      "start": 1647896400,
      "start_time": 1647896400,
      "status": "free"
    },
    {
      "end": 1647897600,
      "end_time": 1647897600,
      "object": "time_slot",
      "start": 1647896700,
      "start_time": 1647896700,
      "status": "free"
    },
    {
      "end": 1647897900,
      "end_time": 1647897900,
      "object": "time_slot",
      "start": 1647897000,
      "start_time": 1647897000,
      "status": "free"
    },
    {
      "end": 1647898200,
      "end_time": 1647898200,
      "object": "time_slot",
      "start": 1647897300,
      "start_time": 1647897300,
      "status": "free"
    },
    {
      "end": 1647898500,
      "end_time": 1647898500,
      "object": "time_slot",
      "start": 1647897600,
      "start_time": 1647897600,
      "status": "free"
    },
    {
      "end": 1647898800,
      "end_time": 1647898800,
      "object": "time_slot",
      "start": 1647897900,
      "start_time": 1647897900,
      "status": "free"
    },
    {
      "end": 1647899100,
      "end_time": 1647899100,
      "object": "time_slot",
      "start": 1647898200,
      "start_time": 1647898200,
      "status": "free"
    },
    {
      "end": 1647899400,
      "end_time": 1647899400,
      "object": "time_slot",
      "start": 1647898500,
      "start_time": 1647898500,
      "status": "free"
    },
    {
      "end": 1647899700,
      "end_time": 1647899700,
      "object": "time_slot",
      "start": 1647898800,
      "start_time": 1647898800,
      "status": "free"
    },
    {
      "end": 1647900000,
      "end_time": 1647900000,
      "object": "time_slot",
      "start": 1647899100,
      "start_time": 1647899100,
      "status": "free"
    }
  ]
}

Check collective availability from multiple providers

This option for collective meetings uses calendars from multiple providers.

curl --location --request POST 'https://api.nylas.com/calendars/availability' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --data-raw '{
    "duration_minutes": 15,
    "start_time": 1647892800,
    "end_time": 1647907200,
    "interval_minutes": 5,
    "emails": [
      "kat@example.com",
      "lamarr@example.com"
    ],
    "free_busy": [],
    "calendars": [
      {
        "account_id": "<ACCOUNT_ID>",
        "calendar_ids": ["<CALENDAR_ID>", "<CALENDAR_ID>"]
      },
      {
        "account_id": "<ACCOUNT_ID>",
        "calendar_ids": ["<CALENDAR_ID>"]
      }
    ]
  }'   
{
  "object": "availability",
  "time_slots": [
    {
      "end": 1647906300,
      "end_time": 1647906300,
      "object": "time_slot",
      "start": 1647905400,
      "start_time": 1647905400,
      "status": "free"
    },
    {
      "end": 1647906600,
      "end_time": 1647906600,
      "object": "time_slot",
      "start": 1647905700,
      "start_time": 1647905700,
      "status": "free"
    },
    {
      "end": 1647906900,
      "end_time": 1647906900,
      "object": "time_slot",
      "start": 1647906000,
      "start_time": 1647906000,
      "status": "free"
    },
    {
      "end": 1647907200,
      "end_time": 1647907200,
      "object": "time_slot",
      "start": 1647906300,
      "start_time": 1647906300,
      "status": "free"
    }
  ]
}

Check collective meetings using Round-Robin with max availability

This example checks availability for participants in the same organization.

curl --location --request POST 'https://api.nylas.com/calendars/availability' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --data-raw '{
    "duration_minutes": 15,
    "start_time": 1647986400,
    "end_time": 1647993600,
    "interval_minutes": 5,
    "emails": [
      "dorothy@example.com",
      "kat@example.com"
    ],
    "free_busy": [],
    "buffer": 30,
    "round_robin": "max-availability",
    "open_hours": [
      {
        "emails": [
          "dorothy@example.com",
          "kat@example.com"
        ],
        "days": [
          0,
          1,
          2,
          3,
          4
        ],
        "timezone": "America/Los_Angeles",
        "start": "10:00",
        "end": "16:00",
        "object_type": "open_hours"
      }
    ]
  }'   
{
  "object": "availability",
  "order": [
    "dorothy@example.com",
    "kat@example.com"
  ],
  "time_slots": [
    {
      "emails": [
        "dorothy@example.com",
        "kat@example.com"
      ],
      "end": 1647987300,
      "end_time": 1647987300,
      "object": "time_slot",
      "start": 1647986400,
      "start_time": 1647986400,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "kat@example.com"
      ],
      "end": 1647987600,
      "end_time": 1647987600,
      "object": "time_slot",
      "start": 1647986700,
      "start_time": 1647986700,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "kat@example.com"
      ],
      "end": 1647987900,
      "end_time": 1647987900,
      "object": "time_slot",
      "start": 1647987000,
      "start_time": 1647987000,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "kat@example.com"
      ],
      "end": 1647988200,
      "end_time": 1647988200,
      "object": "time_slot",
      "start": 1647987300,
      "start_time": 1647987300,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "kat@example.com"
      ],
      "end": 1647988500,
      "end_time": 1647988500,
      "object": "time_slot",
      "start": 1647987600,
      "start_time": 1647987600,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "kat@example.com"
      ],
      "end": 1647988800,
      "end_time": 1647988800,
      "object": "time_slot",
      "start": 1647987900,
      "start_time": 1647987900,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "kat@example.com"
      ],
      "end": 1647989100,
      "end_time": 1647989100,
      "object": "time_slot",
      "start": 1647988200,
      "start_time": 1647988200,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "kat@example.com"
      ],
      "end": 1647989400,
      "end_time": 1647989400,
      "object": "time_slot",
      "start": 1647988500,
      "start_time": 1647988500,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "kat@example.com"
      ],
      "end": 1647989700,
      "end_time": 1647989700,
      "object": "time_slot",
      "start": 1647988800,
      "start_time": 1647988800,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "kat@example.com"
      ],
      "end": 1647990000,
      "end_time": 1647990000,
      "object": "time_slot",
      "start": 1647989100,
      "start_time": 1647989100,
      "status": "free"
    }
  ]
}

Check collective meetings using Round-Robin with max fairness

The examples below are for collective meetings using round-robin with max-fairness. This option returns time slots with at least 50% of available participants. Excluded participants are ordered from most recently booked. If max-fairness has no available slots, the results return information from max-availability.

curl --location --request POST 'https://api.nylas.com/calendars/availability' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --data-raw '{
    "duration_minutes": 15,
    "start_time": 1647986400,
    "end_time": 1647993600,
    "interval_minutes": 5,
    "emails": [
      "dorothy@example.com",
      "kat@example.com",
      "mae@example.com"
    ],
    "free_busy": [],
    "buffer": 30,
    "round_robin": "max-fairness",
    "open_hours": [
      {
        "emails": [
          "dorothy@example.com",
          "kat@example.com",
          "mae@example.com"
        ],
        "days": [
            0,
            1,
            2,
            3,
            4
        ],
        "timezone": "America/Los_Angeles",
        "start": "10:00",
        "end": "16:00",
        "object_type": "open_hours"
      }
    ]
  }'   
{
  "object": "availability",
  "order": [
    "dorothy@example.com",
    "kat@example.com"
  ],
  "time_slots": [
    {
      "emails": [
        "dorothy@example.com",
        "mae@example.com"
      ],
      "end": 1647987300,
      "end_time": 1647987300,
      "object": "time_slot",
      "start": 1647986400,
      "start_time": 1647986400,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "mae@example.com"
      ],
      "end": 1647987600,
      "end_time": 1647987600,
      "object": "time_slot",
      "start": 1647986700,
      "start_time": 1647986700,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "mae@example.com"
      ],
      "end": 1647987900,
      "end_time": 1647987900,
      "object": "time_slot",
      "start": 1647987000,
      "start_time": 1647987000,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "mae@example.com"
      ],
      "end": 1647988200,
      "end_time": 1647988200,
      "object": "time_slot",
      "start": 1647987300,
      "start_time": 1647987300,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "mae@example.com"
      ],
      "end": 1647988500,
      "end_time": 1647988500,
      "object": "time_slot",
      "start": 1647987600,
      "start_time": 1647987600,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "mae@example.com"
      ],
      "end": 1647988800,
      "end_time": 1647988800,
      "object": "time_slot",
      "start": 1647987900,
      "start_time": 1647987900,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "mae@example.com"
      ],
      "end": 1647989100,
      "end_time": 1647989100,
      "object": "time_slot",
      "start": 1647988200,
      "start_time": 1647988200,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "mae@example.com"
      ],
      "end": 1647989400,
      "end_time": 1647989400,
      "object": "time_slot",
      "start": 1647988500,
      "start_time": 1647988500,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "mae@example.com"
      ],
      "end": 1647989700,
      "end_time": 1647989700,
      "object": "time_slot",
      "start": 1647988800,
      "start_time": 1647988800,
      "status": "free"
    },
    {
      "emails": [
        "dorothy@example.com",
        "mae@example.com"
      ],
      "end": 1647990000,
      "end_time": 1647990000,
      "object": "time_slot",
      "start": 1647989100,
      "start_time": 1647989100,
      "status": "free"
    }
  ]
}

Check availability in same organization

The following JSON snippet shows a response to an Availability request made for accounts in the same organization.

{
  "duration_minutes": 30,
  "start_time": 1600890568,
  "end_time": 1600999200,
  "interval_minutes": 10,
  "emails": [
    "tom@example.com",
    "jane@example.com"
  ]
}

Check availability for accounts outside the organization

The following JSON snippet shows a response to an Availability request made to accounts in different organizations.

{
  "duration_minutes": 30,
  "start_time": 1601042400,
  "end_time": 1601085600,
  "interval_minutes": 10,
  "emails": [
    "tom@example.com",
    "jane@example.com"
  ],
  "free_busy": [
    {
      "email": "marie@example.com",
      "object": "free_busy",
      "time_slots": [{
        "start_time": 1601042400,
        "end_time": 1601044200,
        "object": "time_slot",
        "status": "busy"
      }]
    },
    {
      "email": "lamarr@example.com",
      "object": "free_busy",
      "time_slots": [{
        "start_time": 1601042400,
        "end_time": 1601044200,
        "object": "time_slot",
        "status": "busy"
      }]
    },
    {
      "email": "lamarr@example.com",
      "object": "free_busy",
      "time_slots": [{
        "start_time": 1601047800,
        "end_time": 1601051400,
        "object": "time_slot",
        "status": "busy"
      }]
    }
  ]
}

Check availability with open hours

The following JSON snippet shows a response to an Availability request made using open hours.

  • Accounts outside the organization are entered in the free_busy array.
  • /calendars/availability/consecutive requires emails to be entered as a 2D array.
  • Open hours are optional when checking availability.
{
  "duration_minutes": 30,
  "start_time": 1605794400,
  "end_time": 1605826800,
  "interval_minutes": 10,
  "emails": [
    "dorothy@example.com",
    "kat@example.com",
    "mary@example.com"
  ],
  "free_busy": [{
    "email": "ada@example.com",
    "object": "free_busy",
    "time_slots": [{
      "start_time": 1605819600,
      "end_time": 1605821400,
      "object": "time_slot",
      "status": "busy"
    }]
  }],
  "open_hours": [{
    "emails": [
      "dorothy@example.com",
      "kat@example.com",
    ],
    "days": [
      0,
      1,
      2,
      3,
      4,
      5,
      6
    ],
    "timezone": "America/Chicago",
    "start": "10:00",
    "end": "14:00",
    "object_type": "open_hours"
  }]
}

This option uses free_busy object information.

curl --location --request POST 'https://api.nylas.com/calendars/availability' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --data-raw '{
    "duration_minutes": 15,
    "start_time": 1647889200,
    "end_time": 1647900000,
    "interval_minutes": 5,
    "emails": [
      "marie@example.com",
      "ada@example.com",
      "dorothy@example.com"
    ],
    "free_busy": [
      {
        "email": "marie@example.com",
        "object": "free_busy",
        "time_slots": [{
          "start_time": 1647889200,
          "end_time": 1647896400,
          "object": "time_slot",
          "status": "busy"
        }]
      },
      {
        "email": "ada@example.com",
        "object": "free_busy",
        "time_slots": [{
          "start_time": 1647889200,
          "end_time": 1647896400,
          "object": "time_slot",
          "status": "busy"
        }]
      },
      {
        "email": "dorothy@example.com",
        "object": "free_busy",
        "time_slots": [{
          "start_time": 1647889200,
          "end_time": 1647896400,
          "object": "time_slot",
          "status": "busy"
        }]
      }
    ]
  }'   
{
  "object": "availability",
  "time_slots": [
    {
      "end": 1647897300,
      "end_time": 1647897300,
      "object": "time_slot",
      "start": 1647896400,
      "start_time": 1647896400,
      "status": "free"
    },
    {
      "end": 1647897600,
      "end_time": 1647897600,
      "object": "time_slot",
      "start": 1647896700,
      "start_time": 1647896700,
      "status": "free"
    },
    {
      "end": 1647897900,
      "end_time": 1647897900,
      "object": "time_slot",
      "start": 1647897000,
      "start_time": 1647897000,
      "status": "free"
    },
    {
      "end": 1647898200,
      "end_time": 1647898200,
      "object": "time_slot",
      "start": 1647897300,
      "start_time": 1647897300,
      "status": "free"
    },
    {
      "end": 1647898500,
      "end_time": 1647898500,
      "object": "time_slot",
      "start": 1647897600,
      "start_time": 1647897600,
      "status": "free"
    },
    {
      "end": 1647898800,
      "end_time": 1647898800,
      "object": "time_slot",
      "start": 1647897900,
      "start_time": 1647897900,
      "status": "free"
    },
    {
      "end": 1647899100,
      "end_time": 1647899100,
      "object": "time_slot",
      "start": 1647898200,
      "start_time": 1647898200,
      "status": "free"
    },
    {
      "end": 1647899400,
      "end_time": 1647899400,
      "object": "time_slot",
      "start": 1647898500,
      "start_time": 1647898500,
      "status": "free"
    },
    {
      "end": 1647899700,
      "end_time": 1647899700,
      "object": "time_slot",
      "start": 1647898800,
      "start_time": 1647898800,
      "status": "free"
    },
    {
      "end": 1647900000,
      "end_time": 1647900000,
      "object": "time_slot",
      "start": 1647899100,
      "start_time": 1647899100,
      "status": "free"
    }
  ]
}

Check collective availability using Round-Robin with max availability

The example below shows a list of available time slots for a single person along with the list of configured participants.

curl --request POST \
  --url https://api.nylas.com/calendars/availability \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
    "duration_minutes": 60,
    "interval_minutes": 60,
    "start_time": 1634734800,
    "end_time": 1634749200,
    "emails": [],
    "free_busy": [],
    "round_robin": "max-availability",
    "calendars": [
      {
        "account_id": "exampleaccountid1",
        "calendar_ids": [
          "examplecalendaridA",
          "examplecalendaridB"
        ]
      },
      {
        "account_id": "exampleaccountid2",
        "calendar_ids": [
          "examplecalendaridC",
        ]
      }
    ]
  }'   
// This response includes the order of emails for a time slots with multiple emails. The suggestions are preferences based on the most recently created Event.
{
  "object": "availability",
  "order": [
    "account2@example.com",
    "account1@example.com"
  ],
  "time_slots": [
    {
      "emails": [
        "account2@example.com",
        "account1@example.com"
      ],
      "end": 1634738400,
      "object": "time_slot",
      "start": 1634734800,
      "status": "free"
    },
    {
      "emails": [
        "account2@example.com",
        "account1@example.com"
      ],
      "end": 1634742000,
      "object": "time_slot",
      "start": 1634738400,
      "status": "free"
    },
    {
      "emails": [
        "account2@example.com"
      ],
      "end": 1634745600,
      "object": "time_slot",
      "start": 1634742000,
      "status": "free"
    },
    {
      "emails": [
        "account1@example.com"
      ],
      "end": 1634749200,
      "object": "time_slot",
      "start": 1634745600,
      "status": "free"
    }
  ]
}

What's next?