Version:
Only show these results:

Consecutive availability in Nylas v2

Managing availability to schedule events is one of the most common calendar activities. Nylas provides you a way to check availability for multiple meetings so you can build travel itineraries and similar functions.

ℹ️ Availability endpoint is available for v2 Entry, Core, and Plus plans.
ℹ️ Consecutive availablity is available for v2 Core and Plus plans.

Feature support

Endpoint Scopes Provider Availability SDK Support Feature 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.

How to create a Calendar availability request

There are two availability endpoints:

  • /calendars/availability checks multiple calendars to find available time slots for a single meeting.
  • /calendars/availability/consecutive checks to find availability for multiple meetings with several participants. Use this endpoint to build itineraries where participants with the same availability are combined.
ℹ️ Availability endpoint is available for Free, Entry, Core, and Plus plans.

Each endpoint checks the provider's primary calendar.

The requests to check calendar availability and consecutive availability are made of 3 sections: meeting times, free_busy, and open_hours.

First, you’ll review the 3 main sections of a calendar availability POST request. They consist of...

Then you’ll review the response for calendars/availability and /calendars/availability/consecutive. Finally, there are examples of each showing how you can tailor each request to your needs.

Meeting time

Meeting time is used to check availability for the specified meeting time between the participants in the emails array. The emails must be in the same organization. The order the emails are entered does not matter.

Create meeting times for both availability and consecutive availability using the request body:

  • duration_minutes: The total number of minutes the event should last.
  • start_time: Unix timestamp for the beginning meeting.
  • end_time: Unix timestamp for the end of the meeting.
  • interval_minutes: How many minutes it should check for availability. For example, if you need to schedule a 30 minute meeting (duration_minutes) and want to check for availability every 10 minutes (interval_minutes).
  • emails: Emails on the same domain to check. If you are using /calendar/availability it accepts an array of emails. If you are using /calendar/consecutive/availability, it accepts a 2D array of emails.

Consecutive Availability 2D Array

When you are using the /consecutive/availability endpoint, emails are entered as a 2D array.

Example: Meeting time partial request

The following JSON snippets show responses to a meeting time request.

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

Checking Multiple Emails
You can pass in up to 50 emails. Since this endpoint uses synchronous requests (one email at a time), this can slow down response times with large requests. You should also keep your provider rate limits in mind.

Free busy

To check availability for emails not in your organization, you can add them to the free_busy array. Each email address and time slot is its own object. This means if you want to add different busy times for the same email address, you need to add another object for that email address.

Free/Busy works like the free/busy endpoint. You need to know the times the email address outside of your organization is busy. You input these as the start and end times.

Free/Busy is optional for /calendar/availability and /calendar/consecutive/availability. It must still be included as an empty array when not in use.

Create free/busy times for both availability and consecutive availability using the request body:

  • free_busy: A dictionary of free/busy data for users not in your organization. Pass in the emails and times they are busy. Not required as an empty array if checking users in the same organization.
    • email: Email address of guests to check.
    • object: Always free/busy.
      • time_slots: Array containing the start and end times.
        • start_time: Unix timestamp for the beginning of the free/busy window.
        • end_time: Unix timestamp for the end of the free/busy window.
        • object: Always time_slot.
        • status: Always busy.

Free/Busy
Free/Busy is the same for /calendar/availability and /calendar/consecutive/availability.

Example: Free/Busy partial request

The following JSON snippets show responses to a Free/Busy request.

...
  "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"
      }]
    }
  ]
...   
...
  "free_busy": [
    {
      "email": "sample@example.com",
      "object": "free_busy",
      "time_slots": [{
        "start_time": 1605819600,
        "end_time": 1605821400,
        "object": "time_slot",
        "status": "busy"
      }]
    }
  ],
   ...

Open hours

Open hours let you combine calendar availability with preferred availability. For example, meeting time will check for open times on the email’s calendar, and adding open hours lets you add additional unavailability.

When creating an open_hours object keep in mind:

  • Open Hours is optional for calendars/availability and calendars/consecutive/availability.
  • Emails added to open hours must all be in the meeting time emails array.
  • Emails not in the organization cannot use open_hours. They should be input using free_busy.

Create open hours for both availability and consecutive availability using the request body:

  • open_hours: Additional times email accounts are unavailable.
  • emails: Emails on the same domain to check. If you are using /calendar/availability it accepts an array of emails. If you are using calendar/consecutive/availability, it accepts a 2D array of email addresses.
  • days: The days the participants are available entered as an integer. Monday corresponds to 0 and Sunday corresponds to 6.
  • timezone: IANA timezone database formatted string (for example, America/New_York).
  • start: Start time in 24 time clock. Leading 0s are left off. The minimum and maximum start time is 00:00.
  • end: End time in a 24 hour time clock. Leading 0s are left off. The minimum and maximum end time is 00:00.
  • object_type: Always open_hours.

Open Hours

Open Hours is the same for /calendars/availability and /calendars/consecutive/availability.

The following JSON snippets show responses to an open hours request.

...
  "open_hours": [{
    "emails": [
      "jane.doe@example.com"
    ],
    "days": [
      "0"
    ],
    "timezone": "America/Chicago",
    "start": "10:00",
    "end": "14:00",
    "object_type": "open_hours"
  }]   
...
  "open_hours": [{
    "emails": [[
      "jane.doe@example.com"
    ]],
    "days": [
      "0"
    ],
    "timezone": "America/Chicago",
    "start": "10:00",
    "end": "14:00",
    "object_type": "open_hours"
  }]

Availability and Consecutive Availability request

Now that you have gone through each section, you can see the final JSON requests for both endpoints below.

{
  "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"
  }]
}   
{
  "duration_minutes": 30,
  "start_time": 1605794400,
  "end_time": 1605826800,
  "interval_minutes": 10,
  "emails": [[
    "jane.doe@example.com"
  ]],
  "free_busy": [{
    "email": "jane.doe@example.com",
    "object": "free_busy",
    "time_slots": [{
      "start_time": 1605819600,
      "end_time": 1605821400,
      "object": "time_slot",
      "status": "busy"
    }]
  }],
  "open_hours": [{
    "emails": [[
      "string"
    ]],
    "days": [
      "0"
    ],
    "timezone": "America/Chicago",
    "start": "10:00",
    "end": "14:00",
    "object_type": "open_hours"
  }]
}

Availability response

Once you make your POST request, each endpoint will return availability information.

  • Availability: Returns a list of time slots where all participants are available.
  • Consecutive Availability: Returns all possible groupings that share time slots. If only one person is available, it will return in the response. Use this information to schedule groups of people together for meetings.

The following JSON snippets show responses to availability requests.

{
  "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"
    }
  ]
}   
[
  [
    {
      "emails": [
        "kat@example.com",
        "dorothy@example.com"
      ],
      "end_time": 1605794400,
      "start_time": 1605792600
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605796200,
      "start_time": 1605794400
    }
  ],
  [
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605801600,
      "start_time": 1605799800
    },
    {
      "emails": [
        "kat@example.com",
        "dorothy@example.com"
      ],
      "end_time": 1605803400,
      "start_time": 1605801600
    }
  ],
  [
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605802200,
      "start_time": 1605800400
    },
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605804000,
      "start_time": 1605802200
    }
  ],
  [
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605802800,
      "start_time": 1605801000
    },
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605804600,
      "start_time": 1605802800
    }
  ],
  [
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605803400,
      "start_time": 1605801600
    },
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605805200,
      "start_time": 1605803400
    }
  ],
  [
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605803400,
      "start_time": 1605801600
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605805200,
      "start_time": 1605803400
    }
  ],
  [
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605804000,
      "start_time": 1605802200
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605805800,
      "start_time": 1605804000
    }
  ],
  [
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605804000,
      "start_time": 1605802200
    },
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605805800,
      "start_time": 1605804000
    }
  ],
  [
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605804600,
      "start_time": 1605802800
    },
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605806400,
      "start_time": 1605804600
    }
  ],
  [
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605804600,
      "start_time": 1605802800
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605806400,
      "start_time": 1605804600
    }
  ],
  [
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605805200,
      "start_time": 1605803400
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605807000,
      "start_time": 1605805200
    }
  ],
  [
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605805200,
      "start_time": 1605803400
    },
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605807000,
      "start_time": 1605805200
    }
  ],
  [
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605811200,
      "start_time": 1605809400
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605813000,
      "start_time": 1605811200
    }
  ],
  [
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605811800,
      "start_time": 1605810000
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605813600,
      "start_time": 1605811800
    }
  ],
  [
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605812400,
      "start_time": 1605810600
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605814200,
      "start_time": 1605812400
    }
  ],
  [
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605813000,
      "start_time": 1605811200
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605814800,
      "start_time": 1605813000
    }
  ],
  [
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605813000,
      "start_time": 1605811200
    },
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605814800,
      "start_time": 1605813000
    }
  ],
  [
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605813600,
      "start_time": 1605811800
    },
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605815400,
      "start_time": 1605813600
    }
  ],
  [
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605813600,
      "start_time": 1605811800
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605815400,
      "start_time": 1605813600
    }
  ],
  [
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605814200,
      "start_time": 1605812400
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605816000,
      "start_time": 1605814200
    }
  ],
  [
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605814200,
      "start_time": 1605812400
    },
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605816000,
      "start_time": 1605814200
    }
  ],
  [
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605814800,
      "start_time": 1605813000
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605816600,
      "start_time": 1605814800
    }
  ],
  [
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605815400,
      "start_time": 1605813600
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605817200,
      "start_time": 1605815400
    }
  ],
  [
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605816000,
      "start_time": 1605814200
    },
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605817800,
      "start_time": 1605816000
    }
  ],
  [
    {
      "emails": [
        "dorothy@example.com"
      ],
      "end_time": 1605826800,
      "start_time": 1605825000
    },
    {
      "emails": [
        "kat@example.com"
      ],
      "end_time": 1605828600,
      "start_time": 1605826800
    }
  ]
]

Learn More

Review the Availability APIs.

Consecutive availability example responses

Use these examples as a quick reference when making calendar availability requests.

Check availability in same organization

The following JSON snippets show responses to availability requests made to accounts in the same organization.

  • /calendars/availability/consecutive requires emails to be entered as a 2D array.
{
  "duration_minutes": 30,
  "start_time": 1605794400,
  "end_time": 1605826800,
  "interval_minutes": 10,
  "emails": [
    ["dorothy@example.com"],
    ["kat@example.com"]
  ],
  "free_busy": []
}

Check availability for accounts outside the organization

The following JSON snippets show responses to availability requests made to accounts in different organizations.

{
  "duration_minutes": 30,
  "start_time": 1605794400,
  "end_time": 1605826800,
  "interval_minutes": 10,
  "emails": [
    ["dorothy@example.com"],
    ["kat@example.com"]
  ],
  "free_busy": [{
    "email": "charlie@example.com",
    "object": "free_busy",
    "time_slots": [{
      "start_time": 1605819600,
      "end_time": 1605821400,
      "object": "time_slot",
      "status": "busy"
    }]
  }]
}

Check availability with open hours

The following JSON snippets show responses to availability requests 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"]
  ],
  "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": [
      "kat@example.com"
    ],
    "days": [
      0,
      1,
      2,
      3,
      4,
      5,
      6
    ],
    "timezone": "America/Chicago",
    "start": "10:00",
    "end": "14:00",
    "object_type": "open_hours"
  }]
}

Consecutive availability meeting parameter

The /calendars/availability/consecutive accepts a parameter, meetings. Meetings allow an organizer to see consecutive meeting times with breaks in between.

Available times for consecutive meetings

To find meeting times add the meetings array. It will look for meetings times that match and are consecutive between each group of emails. You can also specify meeting length by adding duration_minutes.

The following JSON snippet shows an account's available times for consecutive meetings.

{
  "start_time": 1633374000,
  "end_time": 1633381200,
  "interval_minutes": 15,
  "free_busy": [
    {
      "object": "free_busy",
      "email": "alice@example.com",
      "time_slots": []
    },
    {
      "object": "free_busy",
      "email": "bob@example.com",
      "time_slots": [{
        "status": "busy",
        "start_time": 300,
        "object": "time_slot",
        "end_time": 1699
      }]
    },
    {
      "object": "free_busy",
      "email": "chris@example.com",
      "time_slots": []
    },
    {
      "object": "free_busy",
      "email": "dana@example.com",
      "time_slots": []
    },
    {
      "object": "free_busy",
      "email": "emily@example.com",
      "time_slots": []
    },
    {
      "object": "free_busy",
      "email": "fernando@example.com",
      "time_slots": []
    }
  ],
  "meetings": [
    {
      "emails": [
        "anthony@example.com",
        "belinda@example.com",
        "chase@example.com"
      ],
      "duration_minutes": 45
    },
    {
      "emails": [
        "arthur.exec@example.com",
        "bethany.exec@example.com"
      ],
      "duration_minutes": 15
    },
    {
      "emails": [
        "people.team@example.com"
      ]
    },
    {
      "emails": [
        "technical.recruiter@example.com"
      ]
    }
  ]
}

Available time with gaps

The following JSON code sample will look for meetings that have time slots between them. To specify time between meetings, pass in an empty emails array with duration_minutes. The duration_minutes will indicate the time between the meetings.

{
  "start_time": 1633374000,
  "end_time": 1633381200,
  "interval_minutes": 15,
  "free_busy": [
    {
      "object": "free_busy",
      "email": "alice@example.com",
      "time_slots": []
    },
    {
      "object": "free_busy",
      "email": "bob@example.com",
      "time_slots": [{
        "status": "busy",
        "start_time": 300,
        "object": "time_slot",
        "end_time": 1699
      }]
    },
    {
      "object": "free_busy",
      "email": "chris@example.com",
      "time_slots": []
    },
    {
      "object": "free_busy",
      "email": "dana@example.com",
      "time_slots": []
    },
    {
      "object": "free_busy",
      "email": "emily@example.com",
      "time_slots": []
    },
    {
      "object": "free_busy",
      "email": "fernando@example.com",
      "time_slots": []
    }
  ],
  "meetings": [
    {
      "emails": [
        "anthony@example.com",
        "belinda@example.com",
        "chase@example.com"
      ],
        "duration_minutes": 10
    },
    {
      "emails": [
        "arthur.exec@example.com",
        "bethany.exec@example.com",
      ],
      "duration_minutes": 5
    },
    {
      "emails": [
        "people.team@example.com"
      ]
    },
    {
      "emails": [],
      "duration_minutes": 5,
    }
  ]
}

Meetings array limitations

There are a few things to keep in mind when adding meetings.

  • If meetings.emails is present, then the emails is ignored.

  • If meetings.duration_minutes is present, then duration_minutes is ignored, as in the JSON snippet below, the following behavior is true.

    • The response returns a minimum of 1 and a maximum of 10,000.
    • The maximum number of meetings is 500.
    • If meeting.duration_minutes is used, then duration_minutes is ignored.
    • If meeting.emails is used, then emails is ignored.
    • If meetings.emails is empty, but duration_minutes is present, then it is treated as a meeting gap.
    • Meeting gaps are not scheduled, at the start of the meeting, at the end of the meeting, or next to another gap.
    {
      "start_time": 1633374000,
      "end_time": 1633381200,
      "duration_minutes": 30, // This duration integer is ignored if meetings.duration_minutes are added.
      "interval_minutes": 15,
      "emails": [
        ["jane.doe@example.com", "john.smith@example.com"], // This emails array is ignored, if meetings.emails are added. 
      ],
      "free_busy": [
        {
          "object": "free_busy",
          "email": "alice@example.com",
          "time_slots": []
        },
        {
          "object": "free_busy",
          "email": "bob@example.com",
          "time_slots": [{
            "status": "busy",
            "start_time": 300,
            "object": "time_slot",
            "end_time": 1699
          }]
        },
        {
          "object": "free_busy",
          "email": "chris@example.com",
          "time_slots": []
        },
        {
          "object": "free_busy",
          "email": "dana@example.com",
          "time_slots": []
        },
        {
          "object": "free_busy",
          "email": "emily@example.com",
          "time_slots": []
        },
        {
          "object": "free_busy",
          "email": "fernando@example.com",
          "time_slots": []
        }
      ],
      "meetings": [
        {
          "emails": [
            "anthony@example.com",
            "belinda@example.com",
            "chase@example.com"
          ],
          "duration_minutes": 10
        },
        {
          "emails": [
            "arthur.exec@example.com",
            "bethany.exec@example.com"
          ],
            "duration_minutes": 5
        },
        {
          "emails": [
            "people.team@example.com"
          ]
        },
        {
          "emails": [],
          "duration_minutes": 5,
        }
      ]
    }

What's next?