schedules

Schedules API Reference

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

Endpoints Overview

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /v2/schedules | List all schedules | | POST | /v2/schedules | Create a schedule | | GET | /v2/schedules/default | Get default schedule | | GET | /v2/schedules/{scheduleId} | Get a schedule | | PATCH | /v2/schedules/{scheduleId} | Update a schedule | | DELETE | /v2/schedules/{scheduleId} | Delete a schedule |

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

| Field | Type | Required | Description | |-------|------|----------|-------------| | name | string | Yes | Schedule name | | timeZone | string | Yes | IANA timezone identifier | | isDefault | boolean | No | Set as default schedule | | availability | array | Yes | Weekly availability rules | | dateOverrides | array | No | Date-specific overrides |

Availability Object

| Field | Type | Description | |-------|------|-------------| | days | array | Days of week (0=Sunday, 1=Monday, ..., 6=Saturday) | | startTime | string | Start time in HH:MM format | | endTime | string | End time in HH:MM format |

Date Override Object

| Field | Type | Description | |-------|------|-------------| | date | string | Date in YYYY-MM-DD format | | startTime | string/null | Start time (null = unavailable) | | endTime | string/null | End time (null = unavailable) |

Get Default Schedule

GET /v2/schedules/default

Returns the user's default schedule.

Get a Schedule

GET /v2/schedules/{scheduleId}

Path Parameters

| Parameter | Type | Description | |-----------|------|-------------| | scheduleId | number | Schedule ID |

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 T