Schedules API Reference

Detailed documentation for schedule management endpoints in the Cal.diy API v2.

Endpoints Overview

Understanding Schedules

Schedules define when a user is available for bookings. Key concepts:

• Working Hours: Regular weekly availability (e.g., Mon-Fri 9am-5pm)
• Date Overrides: Exceptions to regular hours (e.g., holiday, special hours)
• Timezone: The timezone in which availability is defined
• Default Schedule: The primary schedule used when no specific schedule is assigned

List Schedules

GET /v2/schedules

Response

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "Working Hours",
      "isDefault": true,
      "timeZone": "America/New_York",
      "workingHours": [
        {
          "days": [1, 2, 3, 4, 5],
          "startTime": 540,
          "endTime": 1020
        }
      ],
      "availability": [
        {
          "id": 1,
          "days": [1, 2, 3, 4, 5],
          "startTime": "1970-01-01T09:00:00.000Z",
          "endTime": "1970-01-01T17:00:00.000Z"
        }
      ],
      "dateOverrides": [],
      "isManaged": false,
      "readOnly": false,
      "isLastSchedule": false
    }
  ]
}

Create a Schedule

POST /v2/schedules

Request Body

{
  "name": "Working Hours",
  "timeZone": "America/New_York",
  "isDefault": true,
  "availability": [
    {
      "days": [1, 2, 3, 4, 5],
      "startTime": "09:00",
      "endTime": "17:00"
    }
  ],
  "dateOverrides": [
    {
      "date": "2024-12-25",
      "startTime": null,
      "endTime": null
    }
  ]
}

Fields

Availability Object

Date Override Object

Get Default Schedule

GET /v2/schedules/default

Returns the user's default schedule.

Get a Schedule

GET /v2/schedules/{scheduleId}

Path Parameters

Update a Schedule

PATCH /v2/schedules/{scheduleId}

Request Body

Only include fields you want to update:

{
  "name": "Updated Schedule Name",
  "availability": [
    {
      "days": [1, 2, 3, 4, 5],
      "startTime": "08:00",
      "endTime": "18:00"
    }
  ]
}

Delete a Schedule

DELETE /v2/schedules/{scheduleId}

Note: You cannot delete your last schedule. At least one schedule must exist.

Common Schedule Patterns

Standard Business Hours (Mon-Fri 9-5)

{
  "name": "Business Hours",
  "timeZone": "America/New_York",
  "availability": [
    {
      "days": [1, 2, 3, 4, 5],
      "startTime": "09:00",
      "endTime": "17:00"
    }
  ]
}

Split Schedule (Morning and Afternoon)

{
  "name": "Split Hours",
  "timeZone": "America/New_York",
  "availability": [
    {
      "days": [1, 2, 3, 4, 5],
      "startTime": "09:00",
      "endTime": "12:00"
    },
    {
      "days": [1, 2, 3, 4, 5],
      "startTime": "14:00",
      "endTime": "18:00"
    }
  ]
}

Different Hours Per Day

{
  "name": "Variable Hours",
  "timeZone": "America/New_York",
  "availability": [
    {
      "days": [1, 3, 5],
      "startTime": "09:00",
      "endTime": "17:00"
    },
    {
      "days": [2, 4],
      "startTime": "10:00",
      "endTime": "19:00"
    }
  ]
}

Weekend Availability

{
  "name": "Weekend Support",
  "timeZone": "America/New_York",
  "availability": [
    {
      "days": [0, 6],
      "startTime": "10:00",
      "endTime": "14:00"
    }
  ]
}

Holiday Override (Unavailable)

{
  "dateOverrides": [
    {
      "date": "2024-12-25",
      "startTime": null,
      "endTime": null
    },
    {
      "date": "2024-01-01",
      "startTime": null,
      "endTime": null
    }
  ]
}

Special Hours Override

{
  "dateOverrides": [
    {
      "date": "2024-12-24",
      "startTime": "09:00",
      "endTime": "12:00"
    }
  ]
}

Organization/Team Schedules

For organization-level schedule management:

List Organization Schedules

GET /v2/organizations/{orgId}/schedules

List User Schedules in Organization

GET /v2/organizations/{orgId}/users/{userId}/schedules

Create User Schedule in Organization

POST /v2/organizations/{orgId}/users/{userId}/schedules

Team Member Schedules

GET /v2/organizations/{orgId}/teams/{teamId}/users/{userId}/schedules

Working Hours Format

The API returns working hours in two formats:

Minutes from Midnight

{
  "workingHours": [
    {
      "days": [1, 2, 3, 4, 5],
      "startTime": 540,
      "endTime": 1020
    }
  ]
}

• 540 = 9:00 AM (9 * 60 minutes)
• 1020 = 5:00 PM (17 * 60 minutes)

ISO Time Format

{
  "availability": [
    {
      "days": [1, 2, 3, 4, 5],
      "startTime": "1970-01-01T09:00:00.000Z",
      "endTime": "1970-01-01T17:00:00.000Z"
    }
  ]
}

When creating/updating, use HH:MM format:

{
  "startTime": "09:00",
  "endTime": "17:00"
}

Best Practices

1. Always specify timezone: Schedules are timezone-aware
2. Use date overrides sparingly: For recurring patterns, create separate schedules
3. Test availability: After creating a schedule, verify with the slots endpoint
4. Consider buffer times: Set buffers on event types, not schedules