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.
- With
free_busy - Using calendars from multiple providers
- Round-robin with
max-availabilityfor participants within the same organization - Round robin with max availability
- Round-robin with
max-fairnessfor participants within the same organization
Feature support
| Endpoint | Scopes | Provider Availability | SDK Support | Feature Availability |
|---|---|---|---|---|
| Availability | calendarcalendar.read_only |
Microsoft |
Python - Open Hours is not supported. | Availability does support Room Resources. Just treat it as an email address when checking availability. |
| Consecutive Availability | calendarcalendar.read_only |
Microsoft |
None | Consecutive Availability does support Room Resources. Just treat it as an email address when checking availability. |
| Free/Busy | calendarcalendar.read_only |
Microsoft |
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": [
"[email protected]"
],
"free_busy": [{
"email": "[email protected]",
"object": "free/busy",
"time_slots": [{
"start_time": 1601042400,
"end_time": 1601044200,
"object": "time_slot",
"status": "busy"
}]
}],
"open_hours": [{
"emails": [
"[email protected]"
],
"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.
- With
free_busy - Using calendars from multiple providers
- Round-robin with
max-availabilityfor participants within the same organization - Round-robin with
max-fairnessfor participants within the same organization
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": [
"[email protected]",
"[email protected]",
"[email protected]"
],
"free_busy": [
{
"email": "[email protected]",
"object": "free_busy",
"time_slots": [
{
"start_time": 1647889200,
"end_time": 1647896400,
"object": "time_slot",
"status": "busy"
}
]
},
{
"email": "[email protected]",
"object": "free_busy",
"time_slots": [{
"start_time": 1647889200,
"end_time": 1647896400,
"object": "time_slot",
"status": "busy"
}]
},
{
"email": "[email protected]",
"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": [
"[email protected]",
"[email protected]"
],
"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": [
"[email protected]",
"[email protected]"
],
"free_busy": [],
"buffer": 30,
"round_robin": "max-availability",
"open_hours": [
{
"emails": [
"[email protected]",
"[email protected]"
],
"days": [
0,
1,
2,
3,
4
],
"timezone": "America/Los_Angeles",
"start": "10:00",
"end": "16:00",
"object_type": "open_hours"
}
]
}' {
"object": "availability",
"order": [
"[email protected]",
"[email protected]"
],
"time_slots": [
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647987300,
"end_time": 1647987300,
"object": "time_slot",
"start": 1647986400,
"start_time": 1647986400,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647987600,
"end_time": 1647987600,
"object": "time_slot",
"start": 1647986700,
"start_time": 1647986700,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647987900,
"end_time": 1647987900,
"object": "time_slot",
"start": 1647987000,
"start_time": 1647987000,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647988200,
"end_time": 1647988200,
"object": "time_slot",
"start": 1647987300,
"start_time": 1647987300,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647988500,
"end_time": 1647988500,
"object": "time_slot",
"start": 1647987600,
"start_time": 1647987600,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647988800,
"end_time": 1647988800,
"object": "time_slot",
"start": 1647987900,
"start_time": 1647987900,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647989100,
"end_time": 1647989100,
"object": "time_slot",
"start": 1647988200,
"start_time": 1647988200,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647989400,
"end_time": 1647989400,
"object": "time_slot",
"start": 1647988500,
"start_time": 1647988500,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647989700,
"end_time": 1647989700,
"object": "time_slot",
"start": 1647988800,
"start_time": 1647988800,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"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": [
"[email protected]",
"[email protected]",
"[email protected]"
],
"free_busy": [],
"buffer": 30,
"round_robin": "max-fairness",
"open_hours": [
{
"emails": [
"[email protected]",
"[email protected]",
"[email protected]"
],
"days": [
0,
1,
2,
3,
4
],
"timezone": "America/Los_Angeles",
"start": "10:00",
"end": "16:00",
"object_type": "open_hours"
}
]
}' {
"object": "availability",
"order": [
"[email protected]",
"[email protected]"
],
"time_slots": [
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647987300,
"end_time": 1647987300,
"object": "time_slot",
"start": 1647986400,
"start_time": 1647986400,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647987600,
"end_time": 1647987600,
"object": "time_slot",
"start": 1647986700,
"start_time": 1647986700,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647987900,
"end_time": 1647987900,
"object": "time_slot",
"start": 1647987000,
"start_time": 1647987000,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647988200,
"end_time": 1647988200,
"object": "time_slot",
"start": 1647987300,
"start_time": 1647987300,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647988500,
"end_time": 1647988500,
"object": "time_slot",
"start": 1647987600,
"start_time": 1647987600,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647988800,
"end_time": 1647988800,
"object": "time_slot",
"start": 1647987900,
"start_time": 1647987900,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647989100,
"end_time": 1647989100,
"object": "time_slot",
"start": 1647988200,
"start_time": 1647988200,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647989400,
"end_time": 1647989400,
"object": "time_slot",
"start": 1647988500,
"start_time": 1647988500,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1647989700,
"end_time": 1647989700,
"object": "time_slot",
"start": 1647988800,
"start_time": 1647988800,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"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": [
"[email protected]",
"[email protected]"
]
} 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": [
"[email protected]",
"[email protected]"
],
"free_busy": [
{
"email": "[email protected]",
"object": "free_busy",
"time_slots": [{
"start_time": 1601042400,
"end_time": 1601044200,
"object": "time_slot",
"status": "busy"
}]
},
{
"email": "[email protected]",
"object": "free_busy",
"time_slots": [{
"start_time": 1601042400,
"end_time": 1601044200,
"object": "time_slot",
"status": "busy"
}]
},
{
"email": "[email protected]",
"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_busyarray. /calendars/availability/consecutiverequires 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": [
"[email protected]",
"[email protected]",
"[email protected]"
],
"free_busy": [{
"email": "[email protected]",
"object": "free_busy",
"time_slots": [{
"start_time": 1605819600,
"end_time": 1605821400,
"object": "time_slot",
"status": "busy"
}]
}],
"open_hours": [{
"emails": [
"[email protected]",
"[email protected]",
],
"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": [
"[email protected]",
"[email protected]",
"[email protected]"
],
"free_busy": [
{
"email": "[email protected]",
"object": "free_busy",
"time_slots": [{
"start_time": 1647889200,
"end_time": 1647896400,
"object": "time_slot",
"status": "busy"
}]
},
{
"email": "[email protected]",
"object": "free_busy",
"time_slots": [{
"start_time": 1647889200,
"end_time": 1647896400,
"object": "time_slot",
"status": "busy"
}]
},
{
"email": "[email protected]",
"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": [
"[email protected]",
"[email protected]"
],
"time_slots": [
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1634738400,
"object": "time_slot",
"start": 1634734800,
"status": "free"
},
{
"emails": [
"[email protected]",
"[email protected]"
],
"end": 1634742000,
"object": "time_slot",
"start": 1634738400,
"status": "free"
},
{
"emails": [
"[email protected]"
],
"end": 1634745600,
"object": "time_slot",
"start": 1634742000,
"status": "free"
},
{
"emails": [
"[email protected]"
],
"end": 1634749200,
"object": "time_slot",
"start": 1634745600,
"status": "free"
}
]
}