---
title: "Create calendar"
method: POST
path: "/v2/calendars"
tags: ["Calendars"]
---

# Create calendar

`POST /v2/calendars`

## Request

- Base URL: `https://api.carecycle.ai`
- URL: `https://api.carecycle.ai/v2/calendars`
- Auth: API key in header `x-api-key`

Create a booking calendar that sets when appointments can be booked and who they go to. Fields keep the older appointmentConfig names.

## Request body

- PostV2CalendarsRequestBody
  - `name` string: Calendar name
  - `description` string, nullable: Markdown-supported description shown on the public booking page
  - `concurrentLimit` integer
  - `appointmentLength` integer
  - `appointmentSpacing` integer
  - `maxOptions` integer
  - `minDate` string, date, nullable: Earliest appointment date. Canonical format: YYYY-MM-DD
  - `maxDate` string, date, nullable: Latest appointment date. Canonical format: YYYY-MM-DD
  - `minHours` integer, nullable
  - `preferredMode` 'timezone' | 'zipcode'
  - `appointmentMode` 'phone_call' | 'in_person' | 'video_call' | 'agent_phone_call'
  - `showCallerIdOnBookingPage` boolean
  - `assignmentMode` 'customer_agent' | 'routing_config' | 'external_transfer'
  - `routingConfigId` string, uuid, nullable: Legacy routing mirror for routing_config assignments. Prefer transferConfigId.
  - `transferConfigId` string, uuid, nullable: Routing group for routing_config and external_transfer assignments
  - `workflows` object[]
    - `id` string, uuid, required
    - `name` string, nullable
    - `enabled` boolean, required
    - `trigger` object, required
      - `anchor` 'event_starts' | 'event_ends', required
      - `offsetMinutes` integer, required
    - `condition` object
      - `kind` 'appointment_status', required
      - `statuses` string[], required
    - `action` union, required
      - object
        - `type` 'sms', required
        - `senderId` string, nullable
        - `template` string, required
      - object
        - `type` 'email', required
        - `senderId` string, nullable
        - `subject` string, required
        - `template` string, required
  - `bookingHours` object[]
    - `startHour` integer, required
    - `startMinute` integer
    - `endHour` integer, required
    - `endMinute` integer
    - `dayOfWeek` integer[], required

## Response `200`

POST /v2/calendars Positive response

- PostV2CalendarsPositiveResponse
  - `appointmentConfig` object, required
    - `id` string, uuid, required
    - `createdAt` string, date-time, nullable, required: Calendar creation time. ISO 8601 timestamp
    - `updatedAt` string, date-time, nullable, required: Calendar last update time. ISO 8601 timestamp
    - `clientId` string, uuid, nullable, required
    - `name` string, nullable, required
    - `description` string, nullable, required
    - `concurrentLimit` integer, required
    - `appointmentLength` integer, required
    - `appointmentSpacing` integer, required
    - `maxOptions` integer, required
    - `minDate` string, date, nullable, required: Earliest appointment date. Canonical format: YYYY-MM-DD
    - `maxDate` string, date, nullable, required: Latest appointment date. Canonical format: YYYY-MM-DD
    - `minHours` integer, nullable, required
    - `preferredMode` 'timezone' | 'zipcode', required
    - `appointmentMode` 'phone_call' | 'in_person' | 'video_call' | 'agent_phone_call', required
    - `showCallerIdOnBookingPage` boolean, required
    - `assignmentMode` 'customer_agent' | 'routing_config' | 'external_transfer', required
    - `routingConfigId` string, uuid, nullable, required
    - `transferConfigId` string, uuid, nullable, required
    - `workflows` object[], required
      - `id` string, uuid, required
      - `name` string, nullable
      - `enabled` boolean, required
      - `trigger` object, required
        - `anchor` 'event_starts' | 'event_ends', required
        - `offsetMinutes` integer, required
      - `condition` object
        - `kind` 'appointment_status', required
        - `statuses` string[], required
      - `action` union, required
        - object
          - `type` 'sms', required
          - `senderId` string, nullable
          - `template` string, required
        - object
          - `type` 'email', required
          - `senderId` string, nullable
          - `subject` string, required
          - `template` string, required
    - `bookingHours` object[], required
      - `startHour` integer, required
      - `startMinute` integer
      - `endHour` integer, required
      - `endMinute` integer
      - `dayOfWeek` integer[], required
    - `createdBy` string, uuid, nullable, required
    - `updatedBy` string, uuid, nullable, required
    - `usageHash` string
    - `usedByResources` object[]
      - `kind` 'transfer' | 'appointment' | 'scenario', required
      - `id` string, uuid, required
      - `name` string, required
    - `activeBookingLinkCount` integer
    - `upcomingAppointmentCount` integer
    - `usedByScenarios` object[]
      - `id` string, uuid, required
      - `name` string, required
    - `readiness` object
      - `ready` boolean, required
      - `issues` object[], required
        - `section` string, required
        - `message` string, required
    - `assignedCampaignCount` number
    - `assignedTransferConfigCount` number
    - `usedByCampaigns` object[]
      - `id` string, required
      - `name` string, required
      - `kind` string, nullable, required
      - `status` string, nullable, required
    - `usedByTransferConfigs` object[]
      - `id` string, required
      - `name` string, required
    - `usedByReceptionist` boolean

## Other responses

- `400`: POST /v2/calendars Negative response 400
- `401`: POST /v2/calendars Negative response 401
- `403`: POST /v2/calendars Negative response 403
- `404`: POST /v2/calendars Negative response 404
- `409`: POST /v2/calendars Negative response 409
- `422`: POST /v2/calendars Negative response 422
- `429`: POST /v2/calendars Negative response 429
- `500`: POST /v2/calendars Negative response 500
- `502`: POST /v2/calendars Negative response 502
- `503`: POST /v2/calendars Negative response 503

---

[API](https://skmtc.dev/carecycle/apis/carecycle-public-api.md) - [All operations](https://skmtc.dev/carecycle/apis/carecycle-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/carecycle/apis/carecycle-public-api/revisions/db390c743c36?raw)