---
title: User Calendar Availability
slug: user-calendar-availability
docTags:
createdAt: 2025-08-14T13:55:58.050Z
---
The users' calendar availability can be accessed to identify suitable time slots and periods for event scheduling.
**This feature depends on the users' [Cronofy](https://www.cronofy.com) connection being active in Jobylon.**
### Create
POST p2/users/calendar-availability/
**Query String Parameters**
None
**Request Payload**
**The request structure is based on cronofy's [Availability Query](https://docs.cronofy.com/developers/api/scheduling/availability/)**
| Name | Type | Mandatory? | Description |
| ---------------- | ------- | ---------- | ------------------------------------------------------------------------------ |
| duration\_min | integer | yes | Duration needed for the event.
Between 1 minute and 480 minutes (8 hours) |
| participants | list | yes | List of **Participants** |
| query\_periods | list | yes | List of **Query Periods** |
| response\_format | string | no | "slots" or "periods"
Default is "slots" |
**Participants**
| Name | Type | Mandatory? | Description |
| -------- | ---- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| members | list | yes | List of **Members** |
| required | list | no | Either a String of "all" to specify that all
members of the group need to be available for a period to be viable, or an Integer to specify the minimum number of the group that must be available. |
**Members**
| Name | Type | Mandatory? | Description |
| ----- | ----- | ---------- | ----------------- |
| email | email | yes | Email of the user |
**Query Periods**
| Name | Type | Mandatory? | Description |
| ----- | -------- | ---------- | ----------------------------------------------------- |
| start | datetime | yes | Lookup initial time in the format `%Y-%m-%dT%H:%M:%S` |
| end | datetime | yes | Lookup final time in the format `%Y-%m-%dT%H:%M:%S` |
**Response**
The response will be a list of available time slot objects
| Name | Type | Description |
| ------------ | -------- | ---------------------------------------------------------------- |
| start | datetime | Initial datetime of the available slot/period |
| end | datetime | Final datetime of the available slot/period |
| participants | list | List of **Participants **available for the slot/period |
**Exceptions**
| Status | Description |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | Bad request
- Invalid field format or data
- A user does not exist
- A user does not belong to a customer account accessible by the Partner
- A user does not have an active connection to Cronofy |
| 403 | Permission denied |
| 405 | Method not supported |
### Example
```curl
curl --request POST \
--url https://staging.jobylon.com/p2/users/calendar-availability/ \
--header 'content-type: application/json' \
--header 'x-app-id: ' \
--header 'x-app-key: ' \
--data '{
"participants": [
{
"members": [
{
"email": "peter.parker@jobylon.com"
},
{
"email": "bruce.wayne@jobylon.com"
}
],
"required": "all"
},
{
"members": [
{
"email": "diana.themyscira@jobylon.com"
},
{
"email": "tony.stark@jobylon.com"
}
],
"required": 1
}
],
"query_periods": [
{
"start": "2025-12-15T09:00:00",
"end": "2025-12-20T20:00:00"
},
{
"start": "2025-12-22T09:00:00",
"end": "2025-12-31T15:30:00"
}
],
"duration_min": 30,
"response_format": "periods"
}'
```