Create a schedule

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

Try it

Create a schedule

cURL

curl --request POST \
  --url https://api.cal.com/v2/organizations/{orgId}/users/{userId}/schedules \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Catch up hours",
  "timeZone": "Europe/Rome",
  "isDefault": true,
  "availability": [
    {
      "days": [
        "Monday",
        "Tuesday"
      ],
      "startTime": "17:00",
      "endTime": "19:00"
    },
    {
      "days": [
        "Wednesday",
        "Thursday"
      ],
      "startTime": "16:00",
      "endTime": "20:00"
    }
  ],
  "overrides": [
    {
      "date": "2024-05-20",
      "startTime": "18:00",
      "endTime": "21:00"
    }
  ]
}
'

201

{
  "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"
      }
    ]
  }
}

Headers

Authorization · string

For non-platform customers - value must be Bearer <token> where <token> is api key prefixed with cal_

x-cal-secret-key · string

For platform customers - OAuth client secret key

x-cal-client-id · string

For platform customers - OAuth client ID

Path Parameters

userId · number · required

Body

application/json

name · string · required

Example:

"Catch up hours"

timeZone · string · required

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

Example:

"Europe/Rome"

isDefault · boolean · 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:

true

availability · object[]

Each object contains days and times when the user is available. If not passed, the default availability is Monday to Friday from 09:00 to 17:00.

Show child attributes

availability. days · enum<string>[] · required

Array of days when schedule is active.

Available options: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday

Example:

["Monday", "Tuesday"]

availability. startTime · string · required

startTime must be a valid time in format HH:MM e.g. 08:00

Example:

"08:00"

availability. endTime · string · required

endTime must be a valid time in format HH:MM e.g. 15:00

Example:

"15:00"

Example:

[
  {
    "days": ["Monday", "Tuesday"],
    "startTime": "17:00",
    "endTime": "19:00"
  },
  {
    "days": ["Wednesday", "Thursday"],
    "startTime": "16:00",
    "endTime": "20:00"
  }
]

overrides · object[]

Need to change availability for a specific date? Add an override.

Show child attributes

overrides. date · string · required

Example:

"2024-05-20"

overrides. startTime · string · required

startTime must be a valid time in format HH:MM e.g. 12:00

Example:

"12:00"

overrides. endTime · string · required

endTime must be a valid time in format HH:MM e.g. 13:00

Example:

"13:00"

Example:

[
  {
    "date": "2024-05-20",
    "startTime": "18:00",
    "endTime": "21:00"
  }
]

Response

201 - application/json

status · enum<string> · required

Available options: success, error

Example:

"success"

data · object · required

Show child attributes

data. id · number · required

Example:

254

data. ownerId · number · required

Example:

478

data. name · string · required

Example:

"Catch up hours"

data. timeZone · string · required

Example:

"Europe/Rome"

data. availability · object[] · required

Show child attributes

data.availability. days · enum<string>[] · required

Array of days when schedule is active.

Available options: Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, Sunday

Example:

["Monday", "Tuesday"]

data.availability. startTime · string · required

startTime must be a valid time in format HH:MM e.g. 08:00

Example:

"08:00"

data.availability. endTime · string · required

endTime must be a valid time in format HH:MM e.g. 15:00

Example:

"15:00"

Example:

[
  {
    "days": ["Monday", "Tuesday"],
    "startTime": "17:00",
    "endTime": "19:00"
  },
  {
    "days": ["Wednesday", "Thursday"],
    "startTime": "16:00",
    "endTime": "20:00"
  }
]

data. isDefault · boolean · required

Example:

true

data. overrides · object[] · required

Show child attributes

data.overrides. date · string · required

Example:

"2024-05-20"

data.overrides. startTime · string · required

startTime must be a valid time in format HH:MM e.g. 12:00

Example:

"12:00"

data.overrides. endTime · string · required

endTime must be a valid time in format HH:MM e.g. 13:00

Example:

"13:00"

Example:

[
  {
    "date": "2024-05-20",
    "startTime": "18:00",
    "endTime": "21:00"
  }
]