Create a schedule

Changed on Apr 15, 2026

  Create a schedule for the authenticated user.

  The point of creating schedules is for event types to be available at specific times.

  The first goal of schedules is to have a default schedule. If you are platform customer and created managed users, then it is important to note that each managed user should have a default schedule.
  1. If you passed `timeZone` when creating managed user, then the default schedule from Monday to Friday from 9AM to 5PM will be created with that timezone. The managed user can then change the default schedule via the `AvailabilitySettings` atom.
  2. If you did not, then we assume you want the user to have this specific schedule right away. You should create a default schedule by specifying
  `"isDefault": true` in the request body. Until the user has a default schedule the user can't be booked nor manage their schedule via the AvailabilitySettings atom.

  The second goal of schedules is to create another schedule that event types can point to. This is useful for when an event is booked because availability is not checked against the default schedule but instead against that specific schedule.
  After creating a non-default schedule, you can update an event type to point to that schedule via the PATCH `event-types/{eventTypeId}` endpoint.

  When specifying start time and end time for each day use the 24 hour format e.g. 08:00, 15:00 etc.

  <Note>Please make sure to pass in the cal-api-version header value as mentioned in the Headers section. Not passing the correct value will default to an older version of this endpoint.</Note>

post/v2/schedules

Request

The document declares no server URL.
Auth: none declared. Required headers: Authorization, cal-api-version

Headers

Authorizationstring required

value must be Bearer <token> where <token> is api key prefixed with cal_ or managed user access token

cal-api-versionstring required

Must be set to 2024-06-11. If not set to this value, the endpoint will default to an older version.

Request body

namestring required

timeZonestring required

Timezone is used to calculate available times when an event using the schedule is booked.

isDefaultboolean required

Each user should have 1 default schedule. If you specified timeZone when creating managed user, then the default schedule will be created with that timezone. Default schedule means that if an event type is not tied to a specific schedule then the default schedule is used.

Example request

{
  "name": "Catch up hours",
  "timeZone": "Europe/Rome",
  "availability": [
    {
      "days": [
        "Monday",
        "Tuesday"
      ],
      "startTime": "17:00",
      "endTime": "19:00"
    },
    {
      "days": [
        "Wednesday",
        "Thursday"
      ],
      "startTime": "16:00",
      "endTime": "20:00"
    }
  ],
  "isDefault": true,
  "overrides": [
    {
      "date": "2024-05-20",
      "startTime": "18:00",
      "endTime": "21:00"
    }
  ]
}

Response

status'success' | 'error' required

Example response

{
  "status": "success",
  "data": {
    "id": 254,
    "ownerId": 478,
    "name": "Catch up hours",
    "timeZone": "Europe/Rome",
    "availability": [
      {
        "days": [
          "Monday",
          "Tuesday"
        ],
        "startTime": "17:00",
        "endTime": "19:00"
      },
      {
        "days": [
          "Wednesday",
          "Thursday"
        ],
        "startTime": "16:00",
        "endTime": "20:00"
      }
    ],
    "isDefault": true,
    "overrides": [
      {
        "date": "2024-05-20",
        "startTime": "18:00",
        "endTime": "21:00"
      }
    ]
  }
}

Changes

Apr 15, 2026v216de9d3eb7b3 Revision changes
- breaking
  removed the enum value Friday of the request property //
- breaking
  removed the enum value Monday of the request property //
- breaking
  removed the enum value Saturday of the request property //
- breaking
  removed the enum value Sunday of the request property //
- breaking
  removed the enum value Thursday of the request property //
- breaking
  removed the enum value Tuesday of the request property //
- breaking
  removed the enum value Wednesday of the request property //
- info
  removed the pattern TIME_FORMAT_HH_MM from the request property //
- info
  removed the pattern TIME_FORMAT_HH_MM from the request property //
- info
  removed the pattern TIME_FORMAT_HH_MM from the request property //
- info
  removed the pattern TIME_FORMAT_HH_MM from the request property //
- info
  removed the Friday enum value from the /// response property for the response status
- info
  removed the Monday enum value from the /// response property for the response status
- info
  removed the Saturday enum value from the /// response property for the response status
- info
  removed the Sunday enum value from the /// response property for the response status
- info
  removed the Thursday enum value from the /// response property for the response status
- info
  removed the Tuesday enum value from the /// response property for the response status
- info
  removed the Wednesday enum value from the /// response property for the response status
- info
  the /// response's property pattern TIME_FORMAT_HH_MM was removed for the status
- info
  the /// response's property pattern TIME_FORMAT_HH_MM was removed for the status
- info
  the /// response's property pattern TIME_FORMAT_HH_MM was removed for the status
- info
  the /// response's property pattern TIME_FORMAT_HH_MM was removed for the status
Sep 26, 2025v2daa3e48bc03a Revision changes
- breaking
  request property // was restricted to a list of enum values
- breaking
  added the pattern TIME_FORMAT_HH_MM to the request property //
- breaking
  added the pattern TIME_FORMAT_HH_MM to the request property //
- breaking
  added the pattern TIME_FORMAT_HH_MM to the request property //
- breaking
  added the pattern TIME_FORMAT_HH_MM to the request property //
- warning
  added the new Friday enum value to the /// response property for the response status
- warning
  added the new Monday enum value to the /// response property for the response status
- warning
  added the new Saturday enum value to the /// response property for the response status
- warning
  added the new Sunday enum value to the /// response property for the response status
- warning
  added the new Thursday enum value to the /// response property for the response status
- warning
  added the new Tuesday enum value to the /// response property for the response status
- warning
  added the new Wednesday enum value to the /// response property for the response status
- info
  added the new Friday enum value to the request property //
- info
  added the new Monday enum value to the request property //
- info
  added the new Saturday enum value to the request property //
- info
  added the new Sunday enum value to the request property //
- info
  added the new Thursday enum value to the request property //
- info
  added the new Tuesday enum value to the request property //
- info
  added the new Wednesday enum value to the request property //
- info
  the /// response's property pattern TIME_FORMAT_HH_MM was added for the status
- info
  the /// response's property pattern TIME_FORMAT_HH_MM was added for the status
- info
  the /// response's property pattern TIME_FORMAT_HH_MM was added for the status
- info
  the /// response's property pattern TIME_FORMAT_HH_MM was added for the status

Operation history