Check Availability

Retrieve available or busy time slots for a calendar and schedule

POST /public/calendar/checkAvailability

Returns available (free) or busy time slots for a given calendar and schedule over a specified date range. Slots are generated from the schedule rules, filtered against existing blocking events, and limited by the max-slots-per-day setting. Supports timezone conversion — when `target_timezone` is provided, all returned slot times are converted to that timezone.

Requires a valid `api_key` in the JSON request body

Parameters

Name	In	Type	Required	Description
`api_key`	body	`string`	Yes	Your Zyntro API key
`calendar_id`	body	`string`	Yes	The UUID of the calendar to check
`schedule_id`	body	`string`	Yes	The UUID of the schedule (defines available time blocks, slot duration, and gap between slots)
`days_ahead`	body	`integer`	No	Number of days to look ahead from the start date. Default: `7`
`start_date`	body	`string`	No	Start date in `YYYY-MM-DD HH:MM:SS` format. Defaults to now.
`mode`	body	`string`	No	What to return: `free` (available slots, default) or `busy` (occupied slots)
`current_timezone`	body	`string`	No	IANA timezone for interpreting the start_date. Default: `UTC`
`target_timezone`	body	`string`	No	IANA timezone for the returned slot times. If omitted, slots are returned in the calendar's configured timezone. Set this to the contact's timezone to show them slots in their local time.

Important: The `target_timezone` field controls what timezone the returned slot times are expressed in. If your contact is in `America/New_York` but the calendar is configured in `Asia/Singapore`, set `target_timezone` to `America/New_York` and the slots will be returned in Eastern time — making them directly presentable to the contact without any client-side conversion.

Request Body

Content-Type: application/json

Example

json

{
    "mode": "free",
    "api_key": "YOUR_API_KEY",
    "days_ahead": 7,
    "calendar_id": "3d21426f-9042-40d9-a0b2-94037f551d51",
    "schedule_id": "8d3be70d-69e1-44c5-9ba7-c551a88f7112",
    "target_timezone": "America/New_York"
}

Code Samples

bash

curl -X POST https://app.zyntrohq.com/public/calendar/checkAvailability \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "calendar_id": "3d21426f-9042-40d9-a0b2-94037f551d51",
    "schedule_id": "8d3be70d-69e1-44c5-9ba7-c551a88f7112",
    "days_ahead": 7,
    "mode": "free",
    "target_timezone": "America/New_York"
  }'

Response

200 Slots retrieved

json

{
    "data": {
        "mode": "free",
        "slots": [
            {
                "end": "2026-04-03 09:30:00",
                "label": "Thursday, Apr 3 at 9:00 AM",
                "start": "2026-04-03 09:00:00"
            },
            {
                "end": "2026-04-03 11:00:00",
                "label": "Thursday, Apr 3 at 10:30 AM",
                "start": "2026-04-03 10:30:00"
            },
            {
                "end": "2026-04-04 14:30:00",
                "label": "Friday, Apr 4 at 2:00 PM",
                "start": "2026-04-04 14:00:00"
            }
        ],
        "end_date": "2026-04-10 00:00:00",
        "slot_count": 12,
        "start_date": "2026-04-03 00:00:00",
        "backup_slots": [
            {
                "end": "2026-04-03 11:30:00",
                "label": "Thursday, Apr 3 at 11:00 AM",
                "start": "2026-04-03 11:00:00"
            }
        ],
        "target_timezone": "America/New_York",
        "current_timezone": "UTC",
        "backup_slot_count": 5
    },
    "status": "success"
}

200 Error

json

{
    "data": [
        "Invalid calendar_id value"
    ],
    "status": "error"
}

Info: When `max_slots_per_day` is configured on the schedule, the endpoint shuffles available slots per day and returns only that many in the main `slots` array. The remaining slots are returned in `backup_slots` — available if the primary slots do not work for the contact. In `busy` mode, no backup slots are returned.

Tip: Each slot includes a `label` field formatted as a human-readable string (e.g., "Thursday, Apr 3 at 9:00 AM"). This label is already in the `target_timezone` and can be presented directly to the contact without additional formatting.

Errors

Code	Message	Resolution
`MISSING_API_KEY`	Missing required parameter api_key The api_key is missing.	Include your API key.
`MISSING_CALENDAR`	Missing required parameter calendar_id The calendar_id is missing.	Include the calendar UUID.
`MISSING_SCHEDULE`	Missing required parameter schedule_id The schedule_id is missing.	Include the schedule UUID.
`INACTIVE_USER`	User account is inactive or suspended The account is not active.	Contact your admin.
`INVALID_ORG`	Invalid organization No org found for the user.	Contact support.
`INVALID_CALENDAR`	Invalid calendar_id value No calendar with that ID exists.	Verify the calendar_id.
`INACTIVE_CALENDAR`	Calendar is inactive or not correctly setup The calendar exists but is not active.	Activate the calendar in Sales > Calendar.
`INVALID_SCHEDULE`	Invalid schedule_id value No schedule with that ID exists.	Verify the schedule_id.
`DATE_ERROR`	End date must be greater than start date The calculated end date is before the start date.	Ensure start_date and days_ahead produce a valid range.

5 min read Updated Apr 2, 2026

Navigation

Check Availability

Parameters

Request Body

Example

Code Samples

Response

Errors