HighLevel Calendar Events API

openapi: 3.2.0
info:
  title: Calendars Calendar Events API
  description: Documentation for Calendars API
  version: '1.0'
  contact: {}
servers:
- url: https://services.leadconnectorhq.com
tags:
- name: Calendar Events
  description: Documentation for Calendars API
paths:
  /calendars/events/appointments:
    post:
      operationId: create-appointment
      summary: Create appointment
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-04-15'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppointmentCreateSchema'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppointmentSchemaResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/BadRequestDTO
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
      tags:
      - Calendar Events
      security:
      - bearer:
        - calendars/events.write
  /calendars/events/appointments/{eventId}:
    put:
      operationId: edit-appointment
      summary: Update Appointment
      description: Update appointment
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-04-15'
      - name: eventId
        required: true
        in: path
        description: Event Id or Instance id. For recurring appointments send masterEventId to modify original series.
        examples:
          example1:
            summary: Event ID
            value: ocQHyuzHvysMo5N5VsXc
          example2:
            summary: Recurring Instance ID
            value: ocQHyuzHvysMo5N5VsXc_1729821600000_1800
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppointmentEditSchema'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppointmentSchemaResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/BadRequestDTO
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
      tags:
      - Calendar Events
      security:
      - bearer:
        - calendars/events.write
    get:
      operationId: get-appointment
      summary: Get Appointment
      description: Get appointment by ID
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-04-15'
      - name: eventId
        required: true
        in: path
        description: Event Id or Instance id. For recurring appointments send masterEventId to modify original series.
        examples:
          example1:
            summary: Event ID
            value: ocQHyuzHvysMo5N5VsXc
          example2:
            summary: Recurring Instance ID
            value: ocQHyuzHvysMo5N5VsXc_1729821600000_1800
        schema:
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCalendarEventSuccessfulResponseDTO'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/BadRequestDTO
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
      tags:
      - Calendar Events
      security:
      - bearer:
        - calendars/events.readonly
  /calendars/events:
    get:
      operationId: get-calendar-events
      summary: Get Calendar Events
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-04-15'
      - name: locationId
        required: true
        in: query
        description: Location Id
        schema:
          example: 0007BWpSzSwfiuSl0tR2
          type: string
      - name: userId
        required: false
        in: query
        description: User Id - Owner of an appointment. Either of userId, groupId or calendarId is required
        schema:
          example: CVokAlI8fgw4WYWoCtQz
          type: string
      - name: calendarId
        required: false
        in: query
        description: Either of calendarId, userId or groupId is required
        schema:
          example: BqTwX8QFwXzpegMve9EQ
          type: string
      - name: groupId
        required: false
        in: query
        description: Either of groupId, calendarId or userId is required
        schema:
          example: ocQHyuzHvysMo5N5VsXc
          type: string
      - name: startTime
        required: true
        in: query
        description: Start Time (in millis)
        schema:
          example: '1680373800000'
          type: string
      - name: endTime
        required: true
        in: query
        description: End Time (in millis)
        schema:
          example: '1680978599999'
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCalendarEventsSuccessfulResponseDTO'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/BadRequestDTO
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
      tags:
      - Calendar Events
      security:
      - bearer:
        - calendars/events.readonly
  /calendars/blocked-slots:
    get:
      operationId: get-blocked-slots
      summary: Get Blocked Slots
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-04-15'
      - name: locationId
        required: true
        in: query
        description: Location Id
        schema:
          example: 0007BWpSzSwfiuSl0tR2
          type: string
      - name: userId
        required: false
        in: query
        description: User Id - Owner of an appointment. Either of userId, groupId or calendarId is required
        schema:
          example: CVokAlI8fgw4WYWoCtQz
          type: string
      - name: calendarId
        required: false
        in: query
        description: Either of calendarId, userId or groupId is required
        schema:
          example: BqTwX8QFwXzpegMve9EQ
          type: string
      - name: groupId
        required: false
        in: query
        description: Either of groupId, calendarId or userId is required
        schema:
          example: ocQHyuzHvysMo5N5VsXc
          type: string
      - name: startTime
        required: true
        in: query
        description: Start Time (in millis)
        schema:
          example: '1680373800000'
          type: string
      - name: endTime
        required: true
        in: query
        description: End Time (in millis)
        schema:
          example: '1680978599999'
          type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetCalendarEventsSuccessfulResponseDTO'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/BadRequestDTO
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
      tags:
      - Calendar Events
      security:
      - bearer:
        - calendars/events.readonly
  /calendars/events/block-slots:
    post:
      operationId: create-block-slot
      summary: Create Block Slot
      description: Create block slot
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-04-15'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockSlotCreateRequestDTO'
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockedSlotSuccessfulResponseDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/BadRequestDTO
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
      tags:
      - Calendar Events
      security:
      - bearer:
        - calendars/events.write
  /calendars/events/block-slots/{eventId}:
    put:
      operationId: edit-block-slot
      summary: Update Block Slot
      description: Update block slot by ID
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-04-15'
      - name: eventId
        required: true
        in: path
        description: Event Id or Instance id. For recurring appointments send masterEventId to modify original series.
        examples:
          example1:
            summary: Event ID
            value: ocQHyuzHvysMo5N5VsXc
          example2:
            summary: Recurring Instance ID
            value: ocQHyuzHvysMo5N5VsXc_1729821600000_1800
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BlockSlotEditRequestDTO'
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockedSlotSuccessfulResponseDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/BadRequestDTO
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
      tags:
      - Calendar Events
      security:
      - bearer:
        - calendars/events.write
  /calendars/events/{eventId}:
    delete:
      operationId: delete-event
      summary: Delete Event
      description: Delete event by ID
      parameters:
      - name: Version
        in: header
        description: API Version
        required: true
        schema:
          type: string
          enum:
          - '2021-04-15'
      - name: eventId
        required: true
        in: path
        description: Event Id or Instance id. For recurring appointments send masterEventId to modify original series.
        examples:
          example1:
            summary: Event ID
            value: ocQHyuzHvysMo5N5VsXc
          example2:
            summary: Recurring Instance ID
            value: ocQHyuzHvysMo5N5VsXc_1729821600000_1800
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteAppointmentSchema'
      responses:
        '201':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteEventSuccessfulResponseDto'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/BadRequestDTO
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: ../common/common-schemas.json#/components/schemas/UnauthorizedDTO
      tags:
      - Calendar Events
      security:
      - bearer:
        - calendars/events.write
components:
  schemas:
    GetCalendarEventSuccessfulResponseDTO:
      type: object
      properties:
        event:
          $ref: '#/components/schemas/CalendarEventDTO'
    CalendarEventDTO:
      type: object
      properties:
        id:
          type: string
          description: Event Id or Instance id for a recurring event
          examples:
          - ocQHyuzHvysMo5N5VsXc
          - ocQHyuzHvysMo5N5VsXc_1729821600000_1800
        address:
          type: string
          description: Calendar Event address
          example: https://meet.google.com/yqp-gogr-wve
        title:
          type: string
          description: Calendar Event title
          example: Appointment with GHL Dev team
        calendarId:
          type: string
          description: Calendar ID
          example: BqTwX8QFwXzpegMve9EQ
        locationId:
          type: string
          description: Location ID
          example: 0007BWpSzSwfiuSl0tR2
        contactId:
          type: string
          description: Contact ID
          example: 9NkT25Vor1v4aQatFsv2
        groupId:
          type: string
          description: Group ID
          example: 9NkT25Vor1v4aQatFsv2
        appointmentStatus:
          type: string
          description: Appointment Status
          example: confirmed
        assignedUserId:
          type: string
          description: AssignedUser - the primary owner of an appointment
          example: YlWd2wuCAZQzh2cH1fVZ
        users:
          description: Users - the secondary owners of an appointment.
          example:
          - YlWd2wuCAZQzh2cH1fVZ
          - 9NkT25Vor1v4aQatFsv2
          type: array
          items:
            type: string
        notes:
          type: string
          description: Notes
          example: Some dummy note
        description:
          type: string
          description: Description
          example: Some dummy description
        isRecurring:
          type: boolean
          description: true if the event is recurring otherwise false
          example: 'true'
        rrule:
          type: string
          description: RRULE as per the iCalendar (RFC 5545) specification for recurring events. DTSTART is not required, instance ids are calculated on the basis of startTime of the event.
          examples:
          - RRULE:FREQ=DAILY;INTERVAL=1;COUNT=5
          - 'RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20210623T043000Z

            EXDATE:20211105T040000Z,20211105T040000Z'
        startTime:
          type: object
          description: Start Time
          example: '2023-09-25T16:00:00+05:30'
        endTime:
          type: object
          description: End Time
          example: '2023-09-25T16:00:00+05:30'
        dateAdded:
          type: object
          description: Date Added
          example: '2023-09-25T16:00:00+05:30'
        dateUpdated:
          type: object
          description: Date Updated
          example: '2023-09-25T16:00:00+05:30'
        assignedResources:
          description: Ids of associated resources rooms and/or equipments
          type: array
          items:
            type: string
        createdBy:
          description: Appointment booked by metadata
          allOf:
          - $ref: '#/components/schemas/CreatedOrUpdatedBy'
        masterEventId:
          type: string
          description: Master event id for a recurring instance
          example: ocWd2wuBGAQzh2cH1fSZ
      required:
      - id
      - title
      - calendarId
      - locationId
      - contactId
      - groupId
      - appointmentStatus
      - assignedUserId
      - users
      - startTime
      - endTime
      - dateAdded
      - dateUpdated
    AppointmentEditSchema:
      type: object
      properties:
        title:
          type: string
          description: Title
          example: Test Event
        meetingLocationType:
          type: string
          description: "Meeting location type. \n- If `address` is provided in the request body, the `meetingLocationType` defaults to **custom**."
          example: custom
          enum:
          - custom
          - zoom
          - gmeet
          - phone
          - address
          - ms_teams
          - google
        meetingLocationId:
          type: string
          description: 'The unique identifier for the meeting location.

            - This value can be found in `calendar.locationConfigurations`or `calendar.teamMembers[].locationConfigurations`'
          example: custom_0
          default: default
        overrideLocationConfig:
          type: boolean
          description: 'Flag to override location config

            - **false** - If only `meetingLocationId` is provided

            - **true** - If only `meetingLocationType` is provided

            '
          example: true
        appointmentStatus:
          type: string
          example: confirmed
          enum:
          - new
          - confirmed
          - cancelled
          - showed
          - noshow
          - invalid
        assignedUserId:
          type: string
          description: Assigned User Id
          example: 0007BWpSzSwfiuSl0tR2
        description:
          type: string
          description: Appointment Description
          example: Booking a call to discuss the project
        address:
          type: string
          description: Appointment Address
          example: Zoom
        ignoreDateRange:
          type: boolean
          description: If set to true, the minimum scheduling notice and date range would be ignored
          example: false
        toNotify:
          type: boolean
          description: If set to false, the automations will not run
          example: false
        ignoreFreeSlotValidation:
          type: boolean
          description: If true the time slot validation would be avoided for any appointment creation (even the ignoreDateRange)
          example: true
        rrule:
          type: string
          description: RRULE as per the iCalendar (RFC 5545) specification for recurring events. DTSTART is not required, instance ids are calculated on the basis of startTime of the event. The rrule only be applied if ignoreFreeSlotValidation is true.
          examples:
          - RRULE:FREQ=DAILY;INTERVAL=1;COUNT=5
          - 'RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20210623T043000Z

            EXDATE:20211105T040000Z,20211105T040000Z'
        calendarId:
          type: string
          description: Calendar Id
          example: CVokAlI8fgw4WYWoCtQz
        startTime:
          type: string
          description: Start Time
          example: '2021-06-23T03:30:00+05:30'
        endTime:
          type: string
          description: End Time
          example: '2021-06-23T04:30:00+05:30'
    BlockSlotCreateRequestDTO:
      type: object
      properties:
        title:
          type: string
          description: Title
          example: Test Event
        calendarId:
          type: string
          description: Either calendarId or assignedUserId can be set, not both.
          example: CVokAlI8fgw4WYWoCtQz
        assignedUserId:
          type: string
          description: Either calendarId or assignedUserId can be set, not both.
          example: CVokAlI8fgw4WYWoCtQz
        locationId:
          type: string
          description: Location Id
          example: C2QujeCh8ZnC7al2InWR
        startTime:
          type: string
          description: Start Time
          example: '2021-06-23T03:30:00+05:30'
        endTime:
          type: string
          description: End Time
          example: '2021-06-23T04:30:00+05:30'
      required:
      - calendarId
      - locationId
    DeleteAppointmentSchema:
      type: object
      properties: {}
    AppointmentCreateSchema:
      type: object
      properties:
        title:
          type: string
          description: Title
          example: Test Event
        meetingLocationType:
          type: string
          description: "Meeting location type. \n- If `address` is provided in the request body, the `meetingLocationType` defaults to **custom**."
          example: custom
          enum:
          - custom
          - zoom
          - gmeet
          - phone
          - address
          - ms_teams
          - google
        meetingLocationId:
          type: string
          description: 'The unique identifier for the meeting location.

            - This value can be found in `calendar.locationConfigurations`or `calendar.teamMembers[].locationConfigurations`'
          example: custom_0
          default: default
        overrideLocationConfig:
          type: boolean
          description: 'Flag to override location config

            - **false** - If only `meetingLocationId` is provided

            - **true** - If only `meetingLocationType` is provided

            '
          example: true
        appointmentStatus:
          type: string
          example: confirmed
          enum:
          - new
          - confirmed
          - cancelled
          - showed
          - noshow
          - invalid
        assignedUserId:
          type: string
          description: Assigned User Id
          example: 0007BWpSzSwfiuSl0tR2
        description:
          type: string
          description: Appointment Description
          example: Booking a call to discuss the project
        address:
          type: string
          description: Appointment Address
          example: Zoom
        ignoreDateRange:
          type: boolean
          description: If set to true, the minimum scheduling notice and date range would be ignored
          example: false
        toNotify:
          type: boolean
          description: If set to false, the automations will not run
          example: false
        ignoreFreeSlotValidation:
          type: boolean
          description: If true the time slot validation would be avoided for any appointment creation (even the ignoreDateRange)
          example: true
        rrule:
          type: string
          description: RRULE as per the iCalendar (RFC 5545) specification for recurring events. DTSTART is not required, instance ids are calculated on the basis of startTime of the event. The rrule only be applied if ignoreFreeSlotValidation is true.
          examples:
          - RRULE:FREQ=DAILY;INTERVAL=1;COUNT=5
          - 'RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20210623T043000Z

            EXDATE:20211105T040000Z,20211105T040000Z'
        calendarId:
          type: string
          description: Calendar Id
          example: CVokAlI8fgw4WYWoCtQz
        locationId:
          type: string
          description: Location Id
          example: C2QujeCh8ZnC7al2InWR
        contactId:
          type: string
          description: Contact Id
          example: 0007BWpSzSwfiuSl0tR2
        startTime:
          type: string
          description: Start Time
          example: '2021-06-23T03:30:00+05:30'
        endTime:
          type: string
          description: End Time
          example: '2021-06-23T04:30:00+05:30'
      required:
      - calendarId
      - locationId
      - contactId
      - startTime
    BlockSlotEditRequestDTO:
      type: object
      properties:
        title:
          type: string
          description: Title
          example: Test Event
        calendarId:
          type: string
          description: Either calendarId or assignedUserId can be set, not both.
          example: CVokAlI8fgw4WYWoCtQz
        assignedUserId:
          type: string
          description: Either calendarId or assignedUserId can be set, not both.
          example: CVokAlI8fgw4WYWoCtQz
        locationId:
          type: string
          description: Location Id
          example: C2QujeCh8ZnC7al2InWR
        startTime:
          type: string
          description: Start Time
          example: '2021-06-23T03:30:00+05:30'
        endTime:
          type: string
          description: End Time
          example: '2021-06-23T04:30:00+05:30'
      required:
      - calendarId
      - locationId
    BlockedSlotSuccessfulResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Id
          example: 0TkCdp9PfvLeWKYRRvIz
        locationId:
          type: string
          description: Location Id
          example: C2QujeCh8ZnC7al2InWR
        title:
          type: string
          description: Title
          example: My event
        startTime:
          type: object
          description: Start Time
          example: '2021-06-23T03:30:00+05:30'
        endTime:
          type: object
          description: End Time
          example: '2021-06-23T04:30:00+05:30'
        calendarId:
          type: string
          description: Calendar id
          example: CVokAlI8fgw4WYWoCtQz
        assignedUserId:
          type: string
          description: Assigned User Id
          example: 0007BWpSzSwfiuSl0tR2
      required:
      - id
      - locationId
      - title
      - startTime
      - endTime
    GetCalendarEventsSuccessfulResponseDTO:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/CalendarEventDTO'
    CreatedOrUpdatedBy:
      type: object
      properties:
        userId:
          type: string
          description: The ID of the user who created or updated the appointment
        source:
          type: string
          description: The source of the appointment
      required:
      - source
    DeleteEventSuccessfulResponseDto:
      type: object
      properties:
        succeeded:
          type: boolean
          example: true
    AppointmentSchemaResponse:
      type: object
      properties:
        calendarId:
          type: string
          description: Calendar Id
          example: CVokAlI8fgw4WYWoCtQz
        locationId:
          type: string
          description: Location Id
          example: C2QujeCh8ZnC7al2InWR
        contactId:
          type: string
          description: Contact Id
          example: 0007BWpSzSwfiuSl0tR2
        startTime:
          type: string
          description: Start Time
          example: '2021-06-23T03:30:00+05:30'
        endTime:
          type: string
          description: End Time
          example: '2021-06-23T04:30:00+05:30'
        title:
          type: string
          description: Title
          example: Test Event
        meetingLocationType:
          type: string
          description: Meeting Location Type
          example: custom
          default: default
        appointmentStatus:
          type: string
          example: confirmed
          enum:
          - new
          - confirmed
          - cancelled
          - showed
          - noshow
          - invalid
          - active
          - completed
        assignedUserId:
          type: string
          description: Assigned User Id
          example: 0007BWpSzSwfiuSl0tR2
        address:
          type: string
          description: Appointment Address
          example: Zoom
        isRecurring:
          type: boolean
          description: true if the event is recurring otherwise false
          example: 'true'
        rrule:
          type: string
          description: RRULE as per the iCalendar (RFC 5545) specification for recurring events
          examples:
          - RRULE:FREQ=DAILY;INTERVAL=1;COUNT=5
          - 'RRULE:FREQ=DAILY;INTERVAL=1;UNTIL=20210623T043000Z

            EXDATE:20211105T040000Z,20211105T040000Z'
        id:
          type: string
          description: Id
          example: 0TkCdp9PfvLeWKYRRvIz
      required:
      - calendarId
      - locationId
      - contactId
      - id
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      name: Authorization
      in: header
      description: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.
      type: http
    Location-Access:
      scheme: bearer
      bearerFormat: JWT
      name: Authorization
      in: header
      description: Use the Access Token generated with user type as Sub-Account (OR) Private Integration Token of Sub-Account.
      type: http
    Location-Access-Only:
      scheme: bearer
      bearerFormat: JWT
      name: Authorization
      in: header
      description: Use the Access Token generated with user type as Sub-Account.
      type: http
    Agency-Access:
      scheme: bearer
      bearerFormat: JWT
      name: Authorization
      in: header
      description: Use the Access Token generated with user type as Agency (OR) Private Integration Token of Agency.
      type: http
    Agency-Access-Only:
      scheme: bearer
      bearerFormat: JWT
      name: Authorization
      in: header
      description: Use the Access Token generated with user type as Agency.
      type: http
x-tagGroups:
  name: Calendars
  tags:
  - Calendars
  - Calendar Groups
  - Calendar Events
  - Appointment Notes
  - 'Calendar Resources: Rooms & Equipments'
  - Calendar Notifications
  - Availability