openapi: 3.0.3
info:
  title: TIMIFY Developer API GraphQL Proxy
  description: >-
    HTTP proxy API in front of TIMIFY GraphQL services. Generated from Express
    routes and route analysis docs.
  version: 0.0.4
  contact:
    name: TIMIFY API Team
    email: developers@timify.com
servers:
  - url: https://api.timify.com
    description: Production
  - url: https://api-stg.timify.com
    description: Staging
  - url: http://localhost:3030
    description: Local development
tags:
  - name: Appointments
    description: Endpoints from `appointments` routes module.
  - name: Auth
    description: Endpoints from `auth` routes module.
  - name: Availability
    description: Endpoints from `availability` routes module.
  - name: Booker Services
    description: Endpoints from `booker-services` routes module.
  - name: Companies
    description: Endpoints from `companies` routes module.
  - name: Customers
    description: Endpoints from `customers` routes module.
  - name: Enterprise Customers
    description: Endpoints for enterprise-level customer management.
  - name: Enterprises
    description: Endpoints from `enterprises` routes module.
  - name: Files
    description: Endpoints from `files` routes module.
  - name: Group Services
    description: Endpoints from `group-services` routes module.
  - name: Enterprise Group Services
    description: Endpoints from `group-services-enterprise` routes module.
  - name: ICS
    description: Endpoints from `ics` routes module.
  - name: Notifications
    description: Endpoints from `notifications` routes module.
  - name: Permissions
    description: Endpoints from `permissions` routes module.
  - name: Public
    description: Endpoints from `public` routes module.
  - name: Resources
    description: Endpoints from `resources` routes module.
  - name: Enterprise Resource Categories
    description: Endpoints for enterprise-level resource categories.
  - name: Services
    description: Endpoints from `services` routes module.
  - name: Enterprise Services
    description: Endpoints for enterprise-level service management.
  - name: Statistics
    description: Endpoints from `statistics` routes module.
  - name: Tags
    description: Endpoints from `tags` routes module.
  - name: Timeshifts
    description: Endpoints from `timeshifts` routes module.
  - name: Transactions
    description: Endpoints from `transactions` routes module.
x-tagGroups:
  - name: Identity & Access
    tags:
      - Auth
  - name: Booking & Availability
    tags:
      - Appointments
      - Availability
      - Booker Services
      - Timeshifts
  - name: Customer Management
    tags:
      - Customers
      - Enterprise Customers
  - name: Organization & Enterprise
    tags:
      - Companies
      - Enterprises
      - Permissions
  - name: Service Catalog
    tags:
      - Services
      - Enterprise Services
      - Group Services
      - Enterprise Group Services
  - name: Resource Management
    tags:
      - Resources
      - Enterprise Resource Categories
  - name: Communication & Integrations
    tags:
      - Notifications
      - Files
      - ICS
      - Tags
  - name: Analytics & Finance
    tags:
      - Statistics
      - Transactions
  - name: Public & Utility
    tags:
      - Public
paths:
  /v1/appointments:
    get:
      tags:
        - Appointments
      summary: List appointments
      description: >
        List appointments for resources filtered by a time interval or other
        criteria.


        **Date Requirements:**

        - **Default:** Both `from_date` AND `to_date` are REQUIRED -
        **Exception:** When filtering by appointment IDs using the `ids`
        parameter, date parameters become OPTIONAL - **Time Alternative:** Can
        use `from_time` and `to_time` as an alternative to date parameters (both
        must be provided together) - **Constraint:** Date interval cannot exceed
        365 days


        **Pagination Defaults:**

        - If `page` or `limit` is not provided or is 0, defaults to `page=1` and
        `limit=10000` - To override defaults, provide both `page > 0` and `limit
        > 0`
      operationId: getV1Appointments
      responses:
        '200':
          description: >-
            Returns paginated list of appointments filtered by date range,
            resource, customer, or service with full appointment details.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Appointment'
                  total:
                    type: integer
                    example: 42
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
                  status:
                    type: integer
                    example: 1
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34cd
                    externalId: EXT-APT-001
                    type: BOOKING
                    title: Consultation
                    resourceId: 62ee11a91d66269c365407b1
                    notes: Initial consultation with Dr. Smith
                    color: '#8ebec3'
                    price: 99.99
                    date: 2026-03-06Z
                    duration: 60
                    durationBefore: 15
                    durationAfter: 0
                    startDate: '2026-03-06T10:00:00Z'
                    createdAt: '2026-03-01T09:00:00Z'
                    createdBy: admin-user
                    createdByUserId: 5f4c840b6f1a10012ab34cd
                    createdByScope: company
                    updatedAt: '2026-03-05T14:30:00Z'
                    updatedBy: admin-user
                    updatedByUserId: 5f4c840b6f1a10012ab34cd
                    updatedByScope: company
                    companyName: ACME Corp
                    timestamp: 1710244800
                    isBookable: true
                    isOnlineBooking: false
                    isCourse: false
                    isPaidOnlineWithStripe: false
                    isPaidOnlineWithPaypal: false
                    hasNotifyCustomers: true
                    hasNotifyResources: true
                    maxParticipants: 1
                    participants: 1
                    customers:
                      - id: 6661c401acdc63cf1f63be8d
                        firstName: John
                        lastName: Doe
                        email: john.doe@example.com
                    resources:
                      - id: 62ee11a91d66269c365407b1
                        externalId: RES-001
                        name: Dr. Smith
                        email: dr.smith@example.com
                    serviceId: 647db96538ab9ba43dad308b
                    tags: []
                    chainId: null
                    chainedEvents: []
                    location:
                      type: office
                      title: Main Office
                      value: 123 Main Street
                  - id: 65f4c840b6f1a10012ab34ce
                    externalId: EXT-APT-002
                    type: RESERVATION
                    title: Team Meeting
                    resourceId: 62ee11a91d66269c365407b2
                    notes: Quarterly review session
                    color: '#a476ca'
                    price: null
                    date: 2026-03-08Z
                    duration: 120
                    durationBefore: 0
                    durationAfter: 15
                    startDate: '2026-03-08T14:00:00Z'
                    createdAt: '2026-03-02T10:15:00Z'
                    createdBy: api-integration
                    createdByUserId: 5f4c840b6f1a10012ab34ce
                    createdByScope: company
                    updatedAt: '2026-03-02T10:15:00Z'
                    updatedBy: api-integration
                    updatedByUserId: 5f4c840b6f1a10012ab34ce
                    updatedByScope: company
                    companyName: ACME Corp
                    timestamp: 1710441600
                    isBookable: true
                    isOnlineBooking: true
                    isCourse: false
                    isPaidOnlineWithStripe: false
                    isPaidOnlineWithPaypal: false
                    hasNotifyCustomers: false
                    hasNotifyResources: true
                    maxParticipants: 5
                    participants: 3
                    customers:
                      - id: 6661c401acdc63cf1f63be8e
                        firstName: Jane
                        lastName: Smith
                        email: jane.smith@example.com
                      - id: 6661c401acdc63cf1f63be8f
                        firstName: Bob
                        lastName: Johnson
                        email: bob.johnson@example.com
                    resources:
                      - id: 62ee11a91d66269c365407b2
                        externalId: RES-002
                        name: Conference Room A
                        email: room-a@example.com
                    customfields:
                      - id: cust-field-001
                        type: TEXT
                        label: Department
                        value: Engineering
                    serviceId: 647db96538ab9ba43dad308c
                    tags:
                      - id: tag-001
                        name: Important
                        color: '#FF0000'
                    location:
                      type: zoom
                      title: Zoom Conference
                      value: https://zoom.us/j/123456789
                total: 42
                meta:
                  page: 1
                  limit: 20
                  totalItems: 42
                  totalPages: 3
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: from_date
          in: query
          required: false
          description: >-
            Start date for appointment search in YYYY-MM-DD format. REQUIRED
            unless filtering by appointment IDs using the `ids` parameter. Must
            be less than or equal to `to_date`. Date interval cannot exceed 365
            days.
          schema:
            type: string
            format: date
          example: '2026-03-02'
        - name: to_date
          in: query
          required: false
          description: >-
            End date for appointment search in YYYY-MM-DD format. REQUIRED
            unless filtering by appointment IDs using the `ids` parameter. Must
            be greater than or equal to `from_date`. Date interval cannot exceed
            365 days.
          schema:
            type: string
            format: date
          example: '2026-03-02'
        - name: from_time
          in: query
          required: false
          description: >-
            Start date and time for appointment search in YYYY-MM-DD HH:mm
            format. Use this as an alternative to from_date/to_date. Must be
            provided together with to_time. Must be less than or equal to
            to_time.
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2026-03-02 09:30
        - name: to_time
          in: query
          required: false
          description: >-
            End date and time for appointment search in YYYY-MM-DD HH:mm format.
            Use this as an alternative to from_date/to_date. Must be provided
            together with from_time. Must be greater than or equal to from_time.
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2026-03-02 17:30
        - name: resource_ids
          in: query
          required: false
          description: >-
            Array of resource IDs (MongoDB ObjectIds) to filter appointments by
            assigned resources.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: service_id
          in: query
          required: false
          description: >-
            Service ID (MongoDB ObjectId) to filter appointments by a specific
            service.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: service_ids
          in: query
          required: false
          description: >-
            Array of service IDs (MongoDB ObjectIds) to filter appointments by
            multiple services.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: combination_event_id
          in: query
          required: false
          description: >-
            Combination event ID (MongoDB ObjectId) to filter appointments that
            are part of a multi-service combination event.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: combination_service_id
          in: query
          required: false
          description: >-
            Combination service ID (MongoDB ObjectId) to filter appointments
            that are part of a specific combination service.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: group_service_id
          in: query
          required: false
          description: >-
            Group service ID (MongoDB ObjectId). Filters to appointments that
            are part of a group service (course/workshop).
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: customer_id
          in: query
          required: false
          description: >-
            Customer ID (MongoDB ObjectId) to filter appointments by a specific
            customer.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: customer_ids
          in: query
          required: false
          description: >-
            Array of customer IDs (MongoDB ObjectIds) to filter appointments by
            multiple customers.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: ids
          in: query
          required: false
          description: >-
            Array of appointment IDs (MongoDB ObjectIds) to filter by specific
            appointments. When provided, date parameters (from_date, to_date)
            become optional.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: tag_ids
          in: query
          required: false
          description: >-
            Array of tag IDs (MongoDB ObjectIds) to filter appointments by
            applied tags.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: type
          in: query
          required: false
          description: Filter appointments by booking type.
          schema:
            type: string
            enum:
              - PRIVATE
              - RESERVATION
              - BOOKING
          example: BOOKING
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: timezone
          in: query
          required: false
          description: >-
            IANA timezone string for datetime calculations (e.g.,
            "America/New_York", "Europe/Berlin", "UTC"). Must be a valid IANA
            timezone identifier.
          schema:
            type: string
          example: Europe/Berlin
        - name: search_term
          in: query
          required: false
          description: >-
            Free-text search to filter appointments by title, customer name,
            email, or other text fields.
          schema:
            type: string
        - name: is_course
          in: query
          required: false
          description: >-
            Filter appointments to only return course-type (group service)
            appointments. When true, returns only appointments that are part of
            a group service/course.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |
            curl https://api.timify.com/v1/appointments \
              -H "Authorization: Bearer YOUR_TOKEN" \
              -H "company-id: YOUR_COMPANY_ID" \
              -G -d "from_date=2026-03-01" -d "to_date=2026-03-31"
        - lang: JavaScript
          label: Node.js
          source: |
            const res = await fetch(
              'https://api.timify.com/v1/appointments?from_date=2026-03-01&to_date=2026-03-31',
              { headers: {
                  'Authorization': 'Bearer YOUR_TOKEN',
                  'company-id': 'YOUR_COMPANY_ID'
              }}
            );
            const { data, total } = await res.json();
        - lang: Python
          label: Python
          source: >
            import requests


            resp = requests.get("https://api.timify.com/v1/appointments",
            headers={
                "Authorization": "Bearer YOUR_TOKEN",
                "company-id": "YOUR_COMPANY_ID"
            }, params={"from_date": "2026-03-01", "to_date": "2026-03-31"})

            data = resp.json()
    post:
      tags:
        - Appointments
      summary: Create appointment
      description: >-
        Create a new appointment. Supports single-resource, multi-resource
        (resourceIds), recurring, group-service (course), and external-id modes.


        **Field Requirements:**

        - `title` is conditionally required: omit it only if all of
        `service_id`, `external_service_id`, `duration`, and `duration_pattern`
        are provided

        - `service_id` and `external_service_id` are mutually exclusive

        - `resource_ids` and `external_resource_ids` are mutually exclusive

        - When `is_course=true` the appointment is treated as a group event
        (course/workshop)

        - When `recurring` is provided, both `timezone` and `frequency` fields
        are required


        **Datetime Format:**

        - Use `YYYY-MM-DD HH:mm` format (e.g., "2026-03-15 14:30")

        - Minutes must be divisible by 5 (valid: :00, :05, :10, :15, etc.)
      operationId: postV1Appointments
      responses:
        '201':
          description: Creates new appointment and returns created record with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34d0
                  externalId: null
                  type: BOOKING
                  title: Hair Cut
                  resourceId: 62ee11a91d66269c365407b1
                  notes: Confirmed via API
                  color: '#8ebec3'
                  price: 45
                  date: 2026-03-10Z
                  duration: 60
                  durationBefore: 0
                  durationAfter: 0
                  startDate: '2026-03-10T10:00:00Z'
                  createdAt: '2026-03-07T11:30:00Z'
                  createdBy: api-service
                  createdByUserId: 5f4c840b6f1a10012ab34cd
                  createdByScope: company
                  updatedAt: '2026-03-07T11:30:00Z'
                  updatedBy: api-service
                  updatedByUserId: 5f4c840b6f1a10012ab34cd
                  updatedByScope: company
                  companyName: ACME Corp
                  timestamp: 1710075600
                  isBookable: true
                  isOnlineBooking: false
                  isCourse: false
                  isPaidOnlineWithStripe: false
                  isPaidOnlineWithPaypal: false
                  hasNotifyCustomers: false
                  hasNotifyResources: false
                  maxParticipants: 1
                  participants: 1
                  customers:
                    - id: 6661c401acdc63cf1f63be8d
                      firstName: John
                      lastName: Doe
                      email: john.doe@example.com
                  resources:
                    - id: 62ee11a91d66269c365407b1
                      externalId: null
                      name: Sarah Johnson
                      email: sarah@example.com
                  serviceId: 647db96538ab9ba43dad308b
                  customfields: []
                  tags: []
                  chainId: null
                  chainedEvents: []
                  location: null
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1AppointmentsRequest'
            example:
              resource_ids:
                - 64142cbefe2cfcf6373f2137
              datetime: 2026-03-10 10:00
              service_id: 647db96538ab9ba43dad308b
              customer_id: 6661c401acdc63cf1f63be8d
              notes: Confirmed via API
              has_notify_customers: false
      security:
        - BearerAuth: []
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |
            curl -X POST https://api.timify.com/v1/appointments \
              -H "Authorization: Bearer YOUR_TOKEN" \
              -H "company-id: YOUR_COMPANY_ID" \
              -H "Content-Type: application/json" \
              -d '{
                "resource_ids": ["64142cbefe2cfcf6373f2137"],
                "datetime": "2026-03-10 10:00",
                "service_id": "647db96538ab9ba43dad308b",
                "customer_id": "6661c401acdc63cf1f63be8d"
              }'
        - lang: JavaScript
          label: Node.js
          source: |
            const res = await fetch('https://api.timify.com/v1/appointments', {
              method: 'POST',
              headers: {
                'Authorization': 'Bearer YOUR_TOKEN',
                'company-id': 'YOUR_COMPANY_ID',
                'Content-Type': 'application/json'
              },
              body: JSON.stringify({
                resource_ids: ['64142cbefe2cfcf6373f2137'],
                datetime: '2026-03-10 10:00',
                service_id: '647db96538ab9ba43dad308b',
                customer_id: '6661c401acdc63cf1f63be8d'
              })
            });
            const data = await res.json();
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/appointments/delete/bulk:
    post:
      tags:
        - Appointments
      summary: Bulk delete appointments
      description: >-
        Delete multiple appointments by their IDs in a single request.


        **Notification Behavior:**

        - `has_notify_customers`: Send cancellation notification to all
        customers attached to the appointments

        - `has_notify_resources`: Send cancellation notification to all assigned
        resources

        - `skip_single_emitter`: When true, skip notifications for one-off
        (non-recurring) appointments

        - `skip_multiple_emitter`: When true, skip notifications for recurring
        appointment series


        All notification flags default to false (no notifications sent).
      operationId: postV1AppointmentsDeleteBulk
      responses:
        '201':
          description: >-
            Bulk deletes appointments and returns deletion result with status
            for each record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  deleted:
                    - id: 65f4c840b6f1a10012ab34cd
                      title: Consultation
                      resourceId: 62ee11a91d66269c365407b1
                      startDate: '2026-03-06T10:00:00Z'
                      status: deleted
                    - id: 65f4c840b6f1a10012ab34ce
                      title: Team Meeting
                      resourceId: 62ee11a91d66269c365407b2
                      startDate: '2026-03-08T14:00:00Z'
                      status: deleted
                  failedCount: 0
                  successCount: 2
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1AppointmentsDeleteBulkRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/appointments/import/bulk:
    post:
      tags:
        - Appointments
      summary: Import or update appointments
      description: >-
        Bulk create or update appointments asynchronously. Supports two import
        modes:


        **Direct Import (recommended):**

        - Pass `events` array directly with appointment objects

        - Each object supports all fields from POST /v1/appointments

        - Include `importEventId` for upsert matching (if a record with this ID
        exists, it will be updated)


        **URL-based Import:**

        - Pass `url` pointing to a file containing events (JSON or custom
        format)

        - Optionally pass `secret` for authentication

        - Useful for large imports from external sources


        **Upsert Behavior:**

        - If an appointment with matching `importEventId` exists, it will be
        updated

        - If an appointment with matching `id` exists, it will be updated

        - Otherwise, a new appointment is created


        **Notifications:**

        - `has_notify_customers`: Send notifications to customers for imported
        appointments

        - `has_notify_resources`: Send notifications to assigned resources for
        imported appointments

        - `skip_emitter`: When true, skip all notifications during import

        - Default: No notifications sent
      operationId: postV1AppointmentsImportBulk
      responses:
        '201':
          description: >-
            Bulk imports appointments from external data and returns import
            result with status for each record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  created:
                    - id: 65f4c840b6f1a10012ab34d1
                      externalId: EXT-IMPORT-001
                      title: Imported Appointment
                      resourceId: 62ee11a91d66269c365407b1
                      startDate: '2026-03-15T14:00:00Z'
                      status: created
                      timestamp: 1710518400
                    - id: 65f4c840b6f1a10012ab34d2
                      externalId: EXT-IMPORT-002
                      title: Imported Workshop
                      resourceId: 62ee11a91d66269c365407b2
                      startDate: '2026-03-16T10:00:00Z'
                      status: created
                      timestamp: 1710604800
                  updated:
                    - id: 65f4c840b6f1a10012ab34d3
                      externalId: EXT-IMPORT-003
                      title: Updated Appointment
                      resourceId: 62ee11a91d66269c365407b1
                      startDate: '2026-03-17T15:00:00Z'
                      status: updated
                      timestamp: 1710690000
                  failedCount: 0
                  createdCount: 2
                  updatedCount: 1
                  totalProcessed: 3
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1AppointmentsImportBulkRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/appointments/multiple:
    post:
      tags:
        - Appointments
      summary: Create appointment with combination service
      description: >-
        Create a new multi-service appointment combining multiple services in a
        single booking.


        **Required Fields:**

        - `service_id`: ID of the primary service

        - `duration`: Duration in minutes (must be divisible by 5)

        - `timezone`: IANA timezone identifier (e.g., Europe/Berlin)

        - `combination_services`: Array of service configurations (each must
        have `service_id` and `duration`)


        **Datetime Format:**

        Appointments must be created using the format `YYYY-MM-DD HH:mm` with
        minutes divisible by 5 (e.g., :00, :05, :10, ..., :55). This is NOT ISO
        8601 format—minutes must align to 5-minute intervals.


        **Conditional Fields:**

        - `max_participants`: Required when `is_course=true` and must be ≥1

        - `participants`: Should be provided when `is_course=true`


        **Color Constraint:**

        Must be one of 16 predefined hex codes: #82a774, #b22e53, #ebb65d,
        #95c5a6, #b26492, #cc9e52, #8ebec3, #a476ca, #e5774c, #7684ca, #5d5a79,
        #8b8b8b, #c46f4e, #7b6161, #6882b0, #385f87


        **Recurring Appointments:**

        If `recurring` is provided, it must include:

        - `timezone`: IANA timezone identifier

        - `frequency`: One of DAYS, WEEKS, MONTHS, YEARS


        **Deep Link Configuration:**

        Type must be 'PRIVATE' to enable pre-reservation deep link settings.
      operationId: postV1AppointmentsMultiple
      responses:
        '201':
          description: >-
            Creates multiple appointments in a single request and returns
            created records with assigned IDs.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Appointment'
                  status:
                    type: integer
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34d4
                    externalId: null
                    type: BOOKING
                    title: Consulting Package - Session 1
                    resourceId: 62ee11a91d66269c365407b1
                    color: '#95c5a6'
                    price: 149.99
                    date: 2026-03-15Z
                    duration: 120
                    startDate: '2026-03-15T10:00:00Z'
                    createdAt: '2026-03-07T12:00:00Z'
                    companyName: ACME Corp
                    timestamp: 1710518400
                    isCourse: false
                    isOnlineBooking: false
                    hasNotifyCustomers: true
                    hasNotifyResources: true
                    maxParticipants: 1
                    participants: 1
                    customers:
                      - id: 6661c401acdc63cf1f63be8d
                        firstName: John
                        lastName: Doe
                        email: john.doe@example.com
                    resources:
                      - id: 62ee11a91d66269c365407b1
                        name: Consultant A
                        email: consultant.a@example.com
                    serviceId: 647db96538ab9ba43dad308b
                  - id: 65f4c840b6f1a10012ab34d5
                    externalId: null
                    type: BOOKING
                    title: Consulting Package - Session 2
                    resourceId: 62ee11a91d66269c365407b1
                    color: '#95c5a6'
                    price: 149.99
                    date: 2026-03-22Z
                    duration: 120
                    startDate: '2026-03-22T10:00:00Z'
                    createdAt: '2026-03-07T12:00:00Z'
                    companyName: ACME Corp
                    timestamp: 1710864000
                    isCourse: false
                    isOnlineBooking: false
                    hasNotifyCustomers: true
                    hasNotifyResources: true
                    maxParticipants: 1
                    participants: 1
                    customers:
                      - id: 6661c401acdc63cf1f63be8d
                        firstName: John
                        lastName: Doe
                        email: john.doe@example.com
                    resources:
                      - id: 62ee11a91d66269c365407b1
                        name: Consultant A
                        email: consultant.a@example.com
                    serviceId: 647db96538ab9ba43dad308c
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1AppointmentsMultipleRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/appointments/reservation:
    post:
      tags:
        - Appointments
      summary: Create appointment reservation
      description: >-
        Reserve a time slot for an appointment.


        **Required Fields:**

        - `date`: Appointment date in YYYY-MM-DD format

        - `minute`: Minute of the day (0-1439) when the appointment should
        start. Must be divisible by 5.


        **Conditional Requirements:**

        Either provide `service_id` OR both `title` and `duration`:

        - **Option 1:** Use `service_id` to reserve a time slot for an existing
        service

        - **Option 2:** Provide both `title` and `duration` to reserve a custom
        appointment slot


        **Constraints:**

        - `duration` and `minute` must be divisible by 5 (must align to 5-minute
        intervals)

        - `minute` range: 0-1439 (corresponds to 00:00-23:55)

        - Cannot specify both `service_id` and custom `title`+`duration`


        **Resource Assignment:**

        - Optionally assign resources via `resource_ids` (internal IDs) or
        `external_resource_ids`

        - These arrays should have at least one item if provided
      operationId: postV1AppointmentsReservation
      responses:
        '201':
          description: >-
            Creates reservation-based appointment and returns created record
            with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34d6
                  externalId: null
                  type: RESERVATION
                  title: Reserved Time Slot
                  resourceId: 62ee11a91d66269c365407b1
                  color: '#7684ca'
                  price: null
                  date: 2026-03-12Z
                  duration: 45
                  startDate: '2026-03-12T14:30:00Z'
                  createdAt: '2026-03-07T13:15:00Z'
                  createdBy: api-service
                  companyName: ACME Corp
                  timestamp: 1710255000
                  isCourse: false
                  isOnlineBooking: false
                  hasNotifyCustomers: false
                  hasNotifyResources: false
                  maxParticipants: 1
                  participants: 0
                  customers: []
                  resources:
                    - id: 62ee11a91d66269c365407b1
                      name: Meeting Room B
                      email: room-b@example.com
                  customfields: []
                  tags: []
                  location:
                    type: office
                    title: Main Building
                    value: 456 Oak Avenue
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1AppointmentsReservationRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/appointments/{appointmentId}:
    delete:
      tags:
        - Appointments
      summary: Delete appointment
      description: >-
        Permanently delete an appointment. Supports externalId lookup via
        `?external=1`. Use `has_notify_customers` and `has_notify_resources` to
        send cancellation notifications.
      operationId: deleteV1AppointmentsByAppointmentid
      responses:
        '200':
          description: >-
            Confirms deletion of the appointment and returns the deleted
            appointment record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: appointmentId
          in: path
          required: true
          description: >-
            Appointment ID (MongoDB ObjectId). When `external=1`, this can be an
            external ID instead.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - name: reason
          in: query
          required: false
          description: Reason for deletion. Optional.
          schema:
            type: string
          example: Schedule conflict
        - name: has_notify_customers
          in: query
          required: false
          description: Send cancellation notification to customers. Default is false.
          schema:
            type: boolean
          example: true
        - name: has_notify_resources
          in: query
          required: false
          description: >-
            Send cancellation notification to assigned resources. Default is
            false.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Appointments
      summary: Fetch appointment
      description: Fetch a single appointment by its TIMIFY ID or external ID.
      operationId: getV1AppointmentsByAppointmentid
      responses:
        '200':
          description: >-
            Returns the specified appointment with complete details including
            resource, service, and participant information.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Appointment'
                  status:
                    type: integer
                    example: 1
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: EXT-APT-DETAIL-001
                  type: BOOKING
                  title: Consultation
                  resourceId: 62ee11a91d66269c365407b1
                  notes: Confirmed via API
                  color: '#8ebec3'
                  price: 99.99
                  date: 2026-03-06Z
                  duration: 60
                  durationBefore: 15
                  durationAfter: 0
                  startDate: '2026-03-06T10:00:00Z'
                  createdAt: '2026-03-01T09:00:00Z'
                  createdBy: admin-user
                  createdByUserId: 5f4c840b6f1a10012ab34cd
                  createdByScope: company
                  updatedAt: '2026-03-05T14:30:00Z'
                  updatedBy: admin-user
                  updatedByUserId: 5f4c840b6f1a10012ab34cd
                  updatedByScope: company
                  companyName: ACME Corp
                  timestamp: 1710244800
                  isBookable: true
                  isOnlineBooking: false
                  isCourse: false
                  isPaidOnlineWithStripe: false
                  isPaidOnlineWithPaypal: false
                  hasNotifyCustomers: true
                  hasNotifyResources: true
                  maxParticipants: 1
                  participants: 1
                  customers:
                    - id: 6661c401acdc63cf1f63be8d
                      firstName: John
                      lastName: Smith
                      email: john.smith@example.com
                  singleCustomers: []
                  customfields:
                    - id: cust-field-002
                      type: TEXT
                      label: Reason for Visit
                      value: Annual Check-up
                      isMultiple: false
                  resources:
                    - id: 62ee11a91d66269c365407b1
                      externalId: RES-DOC-001
                      name: Dr. Smith
                      email: dr.smith@example.com
                  serviceId: 647db96538ab9ba43dad308b
                  service: null
                  recurring: null
                  chainId: null
                  chainedEvents: []
                  tags:
                    - id: tag-priority-001
                      name: VIP
                      color: '#FFD700'
                  combination: null
                  metadata: null
                  scheduledForDeletionAt: null
                  location:
                    type: office
                    title: Medical Office
                    value: 789 Health Drive, Suite 100
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: appointmentId
          in: path
          required: true
          description: Appointmentid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Appointments
      summary: Update appointment
      description: >-
        Update an existing appointment with partial updates.


        **Datetime Format:**

        Appointments must be updated using the format `YYYY-MM-DD HH:mm` with
        minutes divisible by 5 (e.g., :00, :05, :10, ..., :55). This is NOT ISO
        8601 format.


        **Partial Updates:**

        Only the fields provided in the request body will be changed. Omitted
        fields remain unchanged.


        **Duration Constraints:**

        - `duration`, `duration_before`, `duration_after`: Must be divisible by
        5

        - `reserve_for`: Must be divisible by 5


        **Conditional Requirements:**

        - `max_participants`: Minimum 1 when `is_course=true`


        **Color Constraint:**

        Must be one of 16 predefined hex codes: #82a774, #b22e53, #ebb65d,
        #95c5a6, #b26492, #cc9e52, #8ebec3, #a476ca, #e5774c, #7684ca, #5d5a79,
        #8b8b8b, #c46f4e, #7b6161, #6882b0, #385f87


        **External ID Lookup:**

        Use `?external=1` query parameter to look up the appointment by
        `externalId` instead of TIMIFY's internal MongoDB ID.
      operationId: patchV1AppointmentsByAppointmentid
      responses:
        '200':
          description: Updates the appointment and returns the updated appointment record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: EXT-APT-UPDATE-001
                  type: BOOKING
                  title: Consultation (Rescheduled)
                  resourceId: 62ee11a91d66269c365407b1
                  notes: Rescheduled to accommodate patient request
                  color: '#8ebec3'
                  price: 99.99
                  date: 2026-03-08Z
                  duration: 90
                  durationBefore: 15
                  durationAfter: 10
                  startDate: '2026-03-08T10:00:00Z'
                  createdAt: '2026-03-01T09:00:00Z'
                  createdBy: admin-user
                  createdByUserId: 5f4c840b6f1a10012ab34cd
                  createdByScope: company
                  updatedAt: '2026-03-07T15:45:00Z'
                  updatedBy: admin-user
                  updatedByUserId: 5f4c840b6f1a10012ab34cd
                  updatedByScope: company
                  companyName: ACME Corp
                  timestamp: 1710330000
                  isBookable: true
                  isOnlineBooking: false
                  isCourse: false
                  isPaidOnlineWithStripe: false
                  isPaidOnlineWithPaypal: false
                  hasNotifyCustomers: true
                  hasNotifyResources: true
                  maxParticipants: 1
                  participants: 1
                  customers:
                    - id: 6661c401acdc63cf1f63be8d
                      firstName: John
                      lastName: Smith
                      email: john.smith@example.com
                  customfields:
                    - id: cust-field-002
                      type: TEXT
                      label: Reason for Visit
                      value: Annual Check-up with Extended Consultation
                      isMultiple: false
                  resources:
                    - id: 62ee11a91d66269c365407b1
                      externalId: RES-DOC-001
                      name: Dr. Smith
                      email: dr.smith@example.com
                  serviceId: 647db96538ab9ba43dad308b
                  tags:
                    - id: tag-priority-001
                      name: VIP
                      color: '#FFD700'
                  location:
                    type: office
                    title: Medical Office
                    value: 789 Health Drive, Suite 100
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: appointmentId
          in: path
          required: true
          description: Appointmentid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1AppointmentsByAppointmentidRequest'
      security:
        - BearerAuth: []
  /v1/auth/company/{appId}:
    get:
      tags:
        - Auth
      summary: Validate company access
      description: >-
        Check whether the provided JWT token has access to the specified app and
        company. Returns 200 if access is valid, 401 otherwise.
      operationId: getV1AuthCompanyByAppid
      responses:
        '200':
          description: >-
            Validates company access and returns confirmation if token has
            access to the app and company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Company access validated
                  value:
                    data:
                      appId: 65f4c840b6f1a10012ab34cd
                      companyId: 65f5d950c7g2b20123bc45de
                      userId: 65f6e062d8h3c31234cd56eg
                      accessGranted: true
                      permissions:
                        - read_appointments
                        - write_appointments
                        - read_customers
                    status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: appId
          in: path
          required: true
          description: Appid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: authorization
          in: header
          required: false
          description: Authorization header value.
          schema:
            type: string
          example: example
        - $ref: '#/components/parameters/CompanyIdHeader'
      security: []
  /v1/auth/refreshtoken:
    get:
      tags:
        - Auth
      summary: Refresh auth token
      description: >
        **DEPRECATED.** Use `POST /v1/auth/refreshtoken` instead.


        You can exchange your refresh token (from the endpoint */auth/token*)
        with a new valid access token. The

        refreshtoken can be sent in the body or in the query params
      deprecated: true
      operationId: getV1AuthRefreshtoken
      responses:
        '200':
          description: Exchanges refresh token for new access token (deprecated endpoint).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
              examples:
                success:
                  summary: Token refreshed
                  value:
                    accessToken: >-
                      eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoU2NvcGUiOiJBUFAiLCJ1c2VySWQiOiI2MzQ4MjYxZGYzNzBhOTBmOGIyMWI0Y2MifQ.q1RIBPbP3InCrLeQnsGbAIB-TbJuSZfDCr2zJ2mna7s
                    refreshToken: >-
                      eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZyZXNoIjp0cnVlfQ.8X_9UiY4Rq65xB1PrigTyEuHLCGOVJnxn_4cMx9hSuY
                    expires: 7200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: refreshtoken
          in: query
          required: true
          description: Refresh token obtained from /v1/auth/token endpoint.
          schema:
            type: string
      security: []
    post:
      tags:
        - Auth
      summary: Refresh auth token
      description: >
        Exchange a refresh token for a new access token.

        The refresh token can be provided in the request body or as a query
        parameter (body takes precedence).

        You obtain the refresh token from POST /v1/auth/token.
      operationId: postV1AuthRefreshtoken
      responses:
        '200':
          description: Exchanges refresh token for new access and refresh tokens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
              examples:
                success:
                  summary: Token refreshed
                  value:
                    accessToken: >-
                      eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoU2NvcGUiOiJBUFAiLCJ1c2VySWQiOiI2MzQ4MjYxZGYzNzBhOTBmOGIyMWI0Y2MifQ.q1RIBPbP3InCrLeQnsGbAIB-TbJuSZfDCr2zJ2mna7s
                    refreshToken: >-
                      eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZyZXNoIjp0cnVlfQ.8X_9UiY4Rq65xB1PrigTyEuHLCGOVJnxn_4cMx9hSuY
                    expires: 7200
        '400':
          description: Bad request. Refresh token is required but was not provided.
          $ref: '#/components/responses/BadRequest'
        '401':
          description: Unauthorized. The refresh token is invalid or expired.
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: refreshtoken
          in: query
          required: false
          description: |
            Refresh token (fallback if not provided in request body).
            Obtained from POST /v1/auth/token endpoint.
          schema:
            type: string
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1AuthRefreshtokenRequest'
      security: []
  /v1/auth/token:
    get:
      tags:
        - Auth
      summary: Get token
      description: >
        **DEPRECATED.** Use `POST /v1/auth/token` instead.


        Get a token and refresh token for access to the TIMIFY developer API.
        The "appId" and "appsecret" values

        can be found in the apps section -> detail page of the app The expires
        value in the result is in seconds.
      deprecated: true
      operationId: getV1AuthToken
      responses:
        '200':
          description: Returns authentication token for the authenticated user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
              example:
                accessToken: >-
                  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoU2NvcGUiOiJBUFAiLCJ1c2VySWQiOiI2N2NhZDdlY2Y3YjJhZjkxMDcwM2RlNGQifQ.fsZA-Vaq8zabp-XShNakSn2mg5PPhbDFlvvzsHLTKUU
                refreshToken: >-
                  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZyZXNoIjp0cnVlfQ.8EpABfQhmBpg-tuWzqX_aANuUJNcmTIYCP1QP8gNfbc
                expires: 7200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: appid
          in: query
          required: true
          description: Your application ID, provided when you register a Dev API app.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: appsecret
          in: query
          required: true
          description: Your application secret, provided when you register a Dev API app.
          schema:
            type: string
      security: []
    post:
      tags:
        - Auth
      summary: Get auth token
      description: >-
        Get a token and refresh token for access to the TIMIFY developer API.
        The "appId" and "appsecret" values can be found in the apps section ->
        detail page of the app The expires value in the result is in seconds.
      operationId: postV1AuthToken
      responses:
        '200':
          description: Authenticates user and returns access and refresh tokens.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthTokenResponse'
              example:
                accessToken: >-
                  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdXRoU2NvcGUiOiJBUFAiLCJ1c2VySWQiOiI2MzQ4MjYxZGYzNzBhOTBmOGIyMWI0Y2MifQ.q1RIBPbP3InCrLeQnsGbAIB-TbJuSZfDCr2zJ2mna7s
                refreshToken: >-
                  eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZyZXNoIjp0cnVlfQ.8X_9UiY4Rq65xB1PrigTyEuHLCGOVJnxn_4cMx9hSuY
                expires: 7200
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1AuthTokenRequest'
      security: []
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |
            curl -X POST https://api.timify.com/v1/auth/token \
              -H "Content-Type: application/json" \
              -d '{"appid": "YOUR_APP_ID", "appsecret": "YOUR_APP_SECRET"}'
        - lang: JavaScript
          label: Node.js
          source: |
            const res = await fetch('https://api.timify.com/v1/auth/token', {
              method: 'POST',
              headers: { 'Content-Type': 'application/json' },
              body: JSON.stringify({
                appid: 'YOUR_APP_ID',
                appsecret: 'YOUR_APP_SECRET'
              })
            });
            const { accessToken, refreshToken, expires } = await res.json();
        - lang: Python
          label: Python
          source: |
            import requests

            resp = requests.post("https://api.timify.com/v1/auth/token", json={
                "appid": "YOUR_APP_ID",
                "appsecret": "YOUR_APP_SECRET"
            })
            data = resp.json()
  /v1/availability:
    get:
      tags:
        - Availability
      summary: >-
        Use this method to retrieve information about the availability of a
        specific service or a group service (ie course, workshop, event)
      description: >-
        For online bookable timeslots for services or group-service use the
        endpoint _GET booker-services/availabilities_ Response parameters: -
        keys 'data.calendarBegin' and 'data.calendarEnd' - this is the allowed
        period for the availability algorithm. Can be adjusted in the web app
        under the section 'Booking setup' - key 'data.onDays' - array of dates
        with available time slots - key 'data.offDays' - array of dates that are
        fully booked - key 'data.slots.times' - array of times that are
        available for appointments ​​​​​​​If besides knowing the days with free
        slots (_onDays_) and those without any (_offDays_), you want to have a
        list of free slots for very specific days, you can use the parameter
        _days[]_ and you will have the list in the response field _slots_
      operationId: getV1Availability
      responses:
        '200':
          description: >-
            Returns availability information for the specified service including
            available time slots and booked dates.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/AvailabilityResponse'
                  status:
                    type: integer
                    example: 1
              examples:
                success:
                  summary: Service availability
                  value:
                    data:
                      calendarBegin: '2026-03-05T11:40:00Z'
                      calendarEnd: '2027-03-05T11:40:00Z'
                      serviceId: 647db96538ab9ba43dad308b
                      serviceName: Hair Cut
                      duration: 60
                      resources:
                        - id: 62ee11a91d66269c365407b1
                          name: John Smith
                          categoryId: 62ee11a91d66269c365407b0
                          categoryName: Stylists
                          orderIndex: 1
                        - id: 62ee11a91d66269c365407b2
                          name: Jane Doe
                          categoryId: 62ee11a91d66269c365407b0
                          categoryName: Stylists
                          orderIndex: 2
                      onDays:
                        - '2026-03-05'
                        - '2026-03-06'
                        - '2026-03-09'
                        - '2026-03-10'
                        - '2026-03-12'
                      offDays:
                        - '2026-03-07'
                        - '2026-03-08'
                      slots:
                        '2026-03-05':
                          - '09:00'
                          - '10:00'
                          - '14:00'
                          - '15:00'
                        '2026-03-06':
                          - '09:30'
                          - '10:30'
                          - '15:00'
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: fields
          in: query
          required: false
          description: >-
            Comma-separated list of fields to include in the response. Supports
            partial response filtering (e.g., "resources,onDays").
          schema:
            type: array
            items:
              type: string
              example: resources
            minItems: 1
          example:
            - resources
            - onDays
            - offDays
        - name: service_id
          in: query
          required: false
          description: >-
            Service ID (MongoDB ObjectId) to check availability for. Must be
            provided, or use duration or durations_pattern.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: duration
          in: query
          required: false
          description: >-
            Duration of the appointment in minutes. Must be provided, or use
            durations_pattern or service_id. Must be divisible by 5.
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 20
        - name: duration_before
          in: query
          required: false
          description: >-
            Buffer time in minutes before the appointment. Must be divisible by
            5.
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 20
        - name: duration_after
          in: query
          required: false
          description: >-
            Buffer time in minutes after the appointment. Must be divisible by
            5.
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 20
        - name: durations_pattern
          in: query
          required: false
          description: >-
            Array of durations in minutes to check availability for. Each value
            must be divisible by 5. Must be provided, or use duration or
            service_id.
          schema:
            type: array
            items:
              type: integer
              multipleOf: 5
              example: 15
            minItems: 1
          example:
            - 15
            - 20
            - 30
        - name: allowance_type
          in: query
          required: false
          description: >-
            Allowance type for availability calculation. Valid values: NONE (no
            allowance), WORKING (working hours), BOOKING (online bookable, sets
            considerOnlineRules internally).
          schema:
            type: string
            enum:
              - NONE
              - WORKING
              - BOOKING
        - name: days
          in: query
          required: false
          description: >-
            Array of specific dates (YYYY-MM-DD format) to retrieve slot
            availability for. If provided, detailed time slots will be returned
            in the response slots field.
          schema:
            type: array
            items:
              type: string
              format: date
              example: '2026-03-02'
            minItems: 1
          example:
            - '2026-03-02'
            - '2026-03-05'
        - name: resource_ids
          in: query
          required: false
          description: >-
            Array of resource IDs (MongoDB ObjectIds) to filter availability.
            Only slots from these resources will be considered.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: sresource_ids
          in: query
          required: false
          description: >-
            Array of selected resource IDs (MongoDB ObjectIds). Pre-selected
            resources to include in the availability calculation.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: timezone
          in: query
          required: false
          description: >-
            Timezone for availability calculation (e.g., Europe/Berlin). If not
            provided, uses the company default timezone.
          schema:
            type: string
          example: Europe/Berlin
        - name: snap_to_grid
          in: query
          required: false
          description: >-
            Interval in minutes to snap available time slots to grid. Rounds
            slot times to nearest interval.
          schema:
            type: integer
            minimum: 1
        - name: from_time
          in: query
          required: false
          description: >-
            Start date and time for filtering available slots (YYYY-MM-DD HH:mm
            format). Must be provided together with to_time parameter.
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2026-03-02 09:30
        - name: to_time
          in: query
          required: false
          description: >-
            End date and time for filtering available slots (YYYY-MM-DD HH:mm
            format). Must be provided together with from_time parameter.
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2026-03-02 17:30
        - name: combination_services
          in: query
          required: false
          description: >-
            Array of service combinations to check availability for. Each item
            can include duration, eventId, resource_ids, and service_id. Used
            for multi-service booking scenarios.
          schema:
            type: array
            items:
              type: object
              properties:
                duration:
                  type: integer
                  description: >-
                    Duration of this service in minutes (must be divisible by
                    5).
                eventId:
                  type: string
                  description: Event ID for this service.
                resource_ids:
                  type: array
                  items:
                    type: string
                  description: Array of resource IDs for this service.
                service_id:
                  type: string
                  description: Service ID for this combination.
            minItems: 1
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/booker-services/appointments/confirm:
    post:
      tags:
        - Booker Services
      summary: Create booking with reservation ID
      description: >-
        Confirm a reservation and convert it into a full appointment with
        customer data.
      operationId: postV1BookerServicesAppointmentsConfirm
      responses:
        '200':
          description: >-
            Confirms reservation and creates appointment, returns confirmation
            with appointment details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Booking confirmed
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      reservationId: 65f5d951c7g2b20123bc45df
                      startDate: '2024-03-15T14:00:00Z'
                      duration: 60
                      serviceId: 65f6e062d8h3c31234cd56eg
                      serviceName: Hair Cut
                      customerId: 65f7f173e9i4d42345de67fh
                      customerName: John Doe
                      customerEmail: john.doe@example.com
                      resourceId: 65f8g284f0j5e53456ef78gi
                      resourceName: Station 1
                      confirmationCode: BOOK-20240315-001
                      status: CONFIRMED
                      createdAt: '2024-03-07T10:30:00Z'
                      ts: 1709823000
                    status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BookerSecretAuth: []
  /v1/booker-services/availabilities:
    get:
      tags:
        - Booker Services
      summary: >-
        Retrieve free bookable dates and times of a specific service or a group
        service
      description: >-
        Bookable timeslots for a service or group service. There are two ways to
        request company information: 1. __company_id__ parameter 2.
        __external_company_id__ with __enterprise_id__ parameters Response
        parameters: - keys 'data.calendarBegin' and 'data.calendarEnd' - this is
        the allowed period for the availability algorithm. Can be adjusted in
        the web app under the section 'Booking setup' - key 'data.onDays' -
        array of dates with available time slots - key 'data.offDays' - array of
        dates that are fully booked - key 'data.slots.times' - array of times
        that are available for appointments To see the open slots for specific
        days, use the _days[]_ parameter. When the __service_id__ is present the
        service object is returned in the response. When the __course_id__ is
        present the course object is returned in the response.
      operationId: getV1BookerServicesAvailabilities
      responses:
        '200':
          description: >-
            Returns available time slots for services based on provided
            date/time and resource filters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              examples:
                success:
                  summary: Service availabilities
                  value:
                    data:
                      - serviceId: 65f6e062d8h3c31234cd56eg
                        serviceName: Hair Cut
                        duration: 60
                        price: 45
                        calendarBegin: '2024-03-15'
                        calendarEnd: '2024-04-30'
                        onDays:
                          - date: '2024-03-18'
                            slots:
                              times:
                                - '09:00'
                                - '09:30'
                                - '10:00'
                                - '14:00'
                                - '15:00'
                          - date: '2024-03-19'
                            slots:
                              times:
                                - '10:00'
                                - '11:00'
                                - '15:30'
                        offDays:
                          - '2024-03-20'
                          - '2024-03-25'
                    total: 1
                    meta:
                      page: 1
                      limit: 10
                      totalItems: 1
                      totalPages: 1
                    status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      security:
        - BookerSecretAuth: []
  /v1/booker-services/booking-status:
    get:
      tags:
        - Booker Services
      summary: Check if an Appointment can be cancelled or reprogrammed.
      description: >-
        Check the status of the appointment, if the appointment can be cancelled
        or rescheduled.
      operationId: getV1BookerServicesBookingStatus
      responses:
        '200':
          description: Returns booking status and information for the specified service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              examples:
                success:
                  summary: Booking status
                  value:
                    data:
                      - appointmentId: 65f4c840b6f1a10012ab34cd
                        status: CONFIRMED
                        startDate: '2024-03-18T09:00:00Z'
                        serviceName: Hair Cut
                        canCancel: true
                        canReschedule: true
                        cancellationDeadlineHours: 24
                        reschedulingDeadlineHours: 24
                        createdAt: '2024-03-07T10:30:00Z'
                    total: 1
                    meta:
                      page: 1
                      limit: 10
                      totalItems: 1
                      totalPages: 1
                    status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      security:
        - BookerSecretAuth: []
  /v1/booker-services/companies:
    get:
      tags:
        - Booker Services
      summary: Retrieve public data for a company or multiple companies.
      description: >-
        Example publicly availble data: - online bookable services - online
        bookable resources - customer fields __note:__ The use of the
        _company_external_id_ field is associated with the _enterprise_id_. This
        means that if you use the first one, it is mandatory to provide the
        second one.
      operationId: getV1BookerServicesCompanies
      responses:
        '200':
          description: >-
            Returns list of companies available for booking with their service
            offerings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              examples:
                success:
                  summary: Bookable companies
                  value:
                    data:
                      - id: 65f4c840b6f1a10012ab34cd
                        name: Main Salon
                        slug: main-salon
                        city: New York
                        state: NY
                        country: USA
                        phone: +1-555-0123
                        email: info@salon.com
                        onlineBookingEnabled: true
                        services:
                          - id: 65f6e062d8h3c31234cd56eg
                            name: Hair Cut
                            duration: 60
                            price: 45
                            isBookable: true
                          - id: 65f7f173e9i4d42345de67fh
                            name: Hair Coloring
                            duration: 120
                            price: 85
                            isBookable: true
                        resources:
                          - id: 65f8g284f0j5e53456ef78gi
                            name: Station 1
                            isBookable: true
                      - id: 65f5d950c7g2b20123bc45de
                        name: Downtown Branch
                        slug: downtown-branch
                        city: Boston
                        state: MA
                        country: USA
                        phone: +1-555-0456
                        onlineBookingEnabled: true
                        services:
                          - id: 65f8g285f1j5e53456ef78gj
                            name: Hair Cut
                            duration: 60
                            price: 45
                            isBookable: true
                    total: 2
                    meta:
                      page: 1
                      limit: 10
                      totalItems: 2
                      totalPages: 1
                    status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      security:
        - BookerSecretAuth: []
  /v1/booker-services/enterprise:
    get:
      tags:
        - Booker Services
      summary: It returns the public information of an enterprise
      description: >-
        Data for an enterprise and branches that are online bookable. _At least
        one of the following fields are required:_ - __enterprise_id__ -
        __enterprise_slug__
      operationId: getV1BookerServicesEnterprise
      responses:
        '200':
          description: Returns enterprise booking configuration and available services.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Enterprise public information
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      slug: beauty-spa-chain
                      name: Beauty & Spa Chain
                      description: Premier beauty and wellness services
                      defaultBrandColor: '#FF6B9D'
                      logo: https://cdn.example.com/logo.png
                      website: https://beautyandspacha.com
                      phone: +1-555-0789
                      email: hello@beautyspa.com
                      onlineBookingEnabled: true
                      branches:
                        - id: 65f4c840b6f1a10012ab34cd
                          name: Main Salon
                          slug: main-salon
                          city: New York
                          state: NY
                          country: USA
                          onlineBookingEnabled: true
                          servicesCount: 12
                          resourcesCount: 8
                        - id: 65f5d950c7g2b20123bc45de
                          name: Downtown Branch
                          slug: downtown-branch
                          city: Boston
                          state: MA
                          country: USA
                          onlineBookingEnabled: true
                          servicesCount: 8
                          resourcesCount: 5
                    status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BookerSecretAuth: []
  /v1/booker-services/reservations:
    post:
      tags:
        - Booker Services
      summary: Reserve a booking in the system
      description: >-
        Reserve an appointment for a timeslot in the future. A reserved
        appointment needs to be confirmed
      operationId: postV1BookerServicesReservations
      responses:
        '201':
          description: >-
            Creates reservation for a service and returns reservation record
            with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Reservation created
                  value:
                    data:
                      id: 65f5d951c7g2b20123bc45df
                      serviceId: 65f6e062d8h3c31234cd56eg
                      serviceName: Hair Cut
                      companyId: 65f4c840b6f1a10012ab34cd
                      startDate: '2024-03-18T09:00:00Z'
                      duration: 60
                      resourceId: 65f8g284f0j5e53456ef78gi
                      resourceName: Station 1
                      status: RESERVED
                      reservationCode: RES-20240307-001
                      expiresAt: '2024-03-08T09:00:00Z'
                      createdAt: '2024-03-07T10:30:00Z'
                      ts: 1709823000
                    status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BookerSecretAuth: []
  /v1/booker-services/reservations/{reservationId}:
    delete:
      tags:
        - Booker Services
      summary: Delete a reservation or an appointment
      description: >-
        An appointment or reservation is only deleteable within a certain time
        period.
      operationId: deleteV1BookerServicesReservationsByReservationid
      responses:
        '200':
          description: >-
            Confirms deletion of the reservation and returns the deleted
            reservation record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Reservation cancelled
                  value:
                    data:
                      id: 65f5d951c7g2b20123bc45df
                      serviceId: 65f6e062d8h3c31234cd56eg
                      serviceName: Hair Cut
                      startDate: '2024-03-18T09:00:00Z'
                      status: CANCELLED
                      cancelledAt: '2024-03-07T11:15:30Z'
                      cancellationReason: Customer requested cancellation
                      ts: 1709823330
                    status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: reservationId
          in: path
          required: true
          description: Reservationid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
      security:
        - BookerSecretAuth: []
  /v1/companies:
    get:
      tags:
        - Companies
      summary: List all companies
      description: >-
        This endpoint fetches company data. This endpoint can be used in the app
        context (with app token) or company context (by the client with its
        company token) __Only one__ of the following parameters is required: -
        company_id - enterprise_id - external_company_id If you want to filter
        by _service_id_ or _external_service_id_ it is __mandatory__ to provide
        __at least__ one parameter from the previous list.
      operationId: getV1Companies
      responses:
        '200':
          description: >-
            Returns paginated list of companies with their details, filtered by
            provided criteria.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              examples:
                success:
                  summary: Companies list
                  value:
                    data:
                      - id: 65f4c840b6f1a10012ab34cd
                        slug: main-salon
                        name: Main Salon
                        externalId: ext-company-001
                        description: Premium hair and beauty salon
                        city: New York
                        state: NY
                        country: USA
                        timezone: America/New_York
                        onlineBookingEnabled: true
                        isActive: true
                        createdAt: '2024-01-15T10:30:00Z'
                        updatedAt: '2024-03-07T14:22:15Z'
                        ts: 1709823735
                      - id: 65f5d950c7g2b20123bc45de
                        slug: branch-downtown
                        name: Downtown Branch
                        externalId: ext-company-002
                        description: Secondary location in downtown area
                        city: Boston
                        state: MA
                        country: USA
                        timezone: America/New_York
                        onlineBookingEnabled: true
                        isActive: true
                        createdAt: '2024-02-20T09:15:00Z'
                        updatedAt: '2024-03-05T11:45:30Z'
                        ts: 1709741130
                    total: 2
                    meta:
                      page: 1
                      limit: 10
                      totalItems: 2
                      totalPages: 1
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: company_id
          in: query
          required: false
          description: Filter companies by company ID. Must be a valid MongoDB ID.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: enterprise_id
          in: query
          required: false
          description: Filter companies by enterprise ID. Must be a valid MongoDB ID.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: enterprise_slug
          in: query
          required: false
          description: Filter companies by enterprise slug (text identifier).
          schema:
            type: string
        - name: external_company_id
          in: query
          required: false
          description: Filter companies by external company ID.
          schema:
            type: string
          example: ext-company-001
        - name: service_id
          in: query
          required: false
          description: Filter companies by service ID. Must be a valid MongoDB ID.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: external_service_id
          in: query
          required: false
          description: Filter companies by external service ID.
          schema:
            type: string
          example: ext-service-001
        - name: enterprise_tag_ids
          in: query
          required: false
          description: >-
            Filter companies by enterprise tag IDs. Comma-separated list of
            valid MongoDB IDs.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: enterprise_tag_external_ids
          in: query
          required: false
          description: >-
            Filter companies by enterprise tag external IDs. Comma-separated
            list of external identifiers.
          schema:
            type: array
            items:
              type: string
              example: ext-tag-001
            minItems: 1
          example:
            - ext-tag-001
        - name: fields
          in: query
          required: false
          description: >-
            Select which company fields to include in the response
            (comma-separated list).
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: company-id
          in: query
          required: false
          description: Filter companies by company ID (alternative naming format).
          schema:
            type: string
        - name: enterprise-id
          in: query
          required: false
          description: Filter companies by enterprise ID (alternative naming format).
          schema:
            type: string
        - name: enterprise-slug
          in: query
          required: false
          description: Filter companies by enterprise slug (alternative naming format).
          schema:
            type: string
        - name: external-company-id
          in: query
          required: false
          description: Filter companies by external company ID (alternative naming format).
          schema:
            type: string
        - name: service-id
          in: query
          required: false
          description: Filter companies by service ID (alternative naming format).
          schema:
            type: string
        - name: external-service-id
          in: query
          required: false
          description: Filter companies by external service ID (alternative naming format).
          schema:
            type: string
        - name: enterprise-tag-ids
          in: query
          required: false
          description: Filter companies by enterprise tag IDs (alternative naming format).
          schema:
            type: string
        - name: enterprise-tag-external-ids
          in: query
          required: false
          description: >-
            Filter companies by enterprise tag external IDs (alternative naming
            format).
          schema:
            type: string
        - name: owner_email
          in: query
          required: false
          description: Filter companies by owner email address.
          schema:
            type: string
            format: email
          example: alex@example.com
        - name: external_company_ids
          in: query
          required: false
          description: >-
            Filter companies by external company IDs. Comma-separated list of
            external identifiers.
          schema:
            type: array
            items:
              type: string
              example: ext-company-001
            minItems: 1
          example:
            - ext-company-001
        - name: company_ids
          in: query
          required: false
          description: >-
            Filter companies by company IDs. Comma-separated list of valid
            MongoDB IDs.
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/companies/onlinestatus:
    put:
      tags:
        - Companies
      summary: Toggle online status of the company
      description: If it is currently activated, it will be deactivated and vice versa.
      operationId: putV1CompaniesOnlinestatus
      responses:
        '200':
          description: >-
            Updates online booking status for the company and returns status
            confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Online status toggled
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      slug: main-salon
                      name: Main Salon
                      onlineBookingEnabled: false
                      updatedAt: '2024-03-07T14:22:15Z'
                      ts: 1709823735
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/companies/statistics:
    get:
      tags:
        - Companies
      summary: Fetch company statistics
      description: Return aggregate booking and usage statistics for the company.
      operationId: getV1CompaniesStatistics
      responses:
        '200':
          description: >-
            Returns company statistics and metrics including usage data and
            performance indicators.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              examples:
                success:
                  summary: Company statistics
                  value:
                    data:
                      - period: '2024-03-07'
                        periodLabel: '2024-03-07'
                        totalAppointments: 24
                        completedAppointments: 20
                        cancelledAppointments: 2
                        noShowAppointments: 2
                        totalCustomers: 18
                        newCustomers: 3
                        recurringBookings: 8
                        totalRevenue: 1240.5
                        onlineBookings: 18
                        offlineBookings: 6
                      - period: '2024-03-06'
                        periodLabel: '2024-03-06'
                        totalAppointments: 19
                        completedAppointments: 18
                        cancelledAppointments: 1
                        noShowAppointments: 0
                        totalCustomers: 15
                        newCustomers: 1
                        recurringBookings: 6
                        totalRevenue: 980.75
                        onlineBookings: 14
                        offlineBookings: 5
                    total: 2
                    meta:
                      page: 1
                      limit: 10
                      totalItems: 2
                      totalPages: 1
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: month
          in: query
          required: false
          description: 'Filter statistics by month (format: MM or 1-12).'
          schema:
            type: string
        - name: year
          in: query
          required: false
          description: 'Filter statistics by year (format: YYYY).'
          schema:
            type: string
        - name: statistics_mode
          in: query
          required: false
          description: Statistics aggregation mode (e.g., DAILY, MONTHLY, YEARLY).
          schema:
            type: string
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/companies/{id}/settings:
    get:
      tags:
        - Companies
      summary: Get settings
      description: Retrieve configurable settings for the company.
      operationId: getV1CompaniesByIdSettings
      responses:
        '200':
          description: >-
            Returns the company settings configuration including preferences and
            options.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Company settings
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      timezone: America/New_York
                      dateFormat: DD/MM/YYYY
                      timeFormat: HH:mm
                      bookingNotifications: true
                      taxRate: 8.5
                      currency: USD
                      supportEmail: support@salon.com
                      supportPhone: +1-555-0123
                      footfall:
                        sunday:
                          isActive: false
                          intervals: []
                        monday:
                          isActive: true
                          intervals:
                            - begin: '08:00'
                              end: '12:00'
                              footfall: GREEN
                            - begin: '12:00'
                              end: '17:00'
                              footfall: YELLOW
                            - begin: '17:00'
                              end: '20:00'
                              footfall: ORANGE
                        tuesday:
                          isActive: true
                          intervals:
                            - begin: '08:00'
                              end: '12:00'
                              footfall: GREEN
                            - begin: '12:00'
                              end: '17:00'
                              footfall: YELLOW
                            - begin: '17:00'
                              end: '20:00'
                              footfall: ORANGE
                        wednesday:
                          isActive: true
                          intervals:
                            - begin: '08:00'
                              end: '12:00'
                              footfall: GREEN
                            - begin: '12:00'
                              end: '17:00'
                              footfall: YELLOW
                            - begin: '17:00'
                              end: '20:00'
                              footfall: ORANGE
                        thursday:
                          isActive: true
                          intervals:
                            - begin: '08:00'
                              end: '12:00'
                              footfall: GREEN
                            - begin: '12:00'
                              end: '17:00'
                              footfall: YELLOW
                            - begin: '17:00'
                              end: '20:00'
                              footfall: ORANGE
                        friday:
                          isActive: true
                          intervals:
                            - begin: '08:00'
                              end: '12:00'
                              footfall: GREEN
                            - begin: '12:00'
                              end: '18:00'
                              footfall: YELLOW
                            - begin: '18:00'
                              end: '21:00'
                              footfall: ORANGE
                        saturday:
                          isActive: true
                          intervals:
                            - begin: '09:00'
                              end: '13:00'
                              footfall: GREEN
                            - begin: '13:00'
                              end: '18:00'
                              footfall: YELLOW
                            - begin: '18:00'
                              end: '20:00'
                              footfall: ORANGE
                      createdAt: '2024-01-15T10:30:00Z'
                      updatedAt: '2024-03-07T14:22:15Z'
                      ts: 1709823735
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: id
          in: path
          required: true
          description: Id path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    put:
      tags:
        - Companies
      summary: Put settings
      description: >-
        This endpoint updates the footfall for a branch or store. It requires
        seven objects, one for each day of the week starting with SUNDAY
        Footfall is determined by a colour scale: * GREEN * YELLOW * ORANGE *
        RED GREEN means low occupancy, RED is maximum occupancy. At high
        occupancy, the number of free slots is reduced. Note: The default
        footfall is GREEN (low occupancy) Example configuration for one day of
        the week: ```json { "isActive": true, "intervals": [ { "begin": "08:00",
        "end": "09:00", "footfall": "GREEN" }, { "begin": "18:00", "end":
        "18:30", "footfall": "YELLOW" }, { "begin": "18:30", "end": "19:30",
        "footfall": "ORANGE" }, { "begin": "19:30", "end": "20:00", "footfall":
        "RED" } ] } ``` If the store is closed or you do not want to specify
        footfall for the day, the data structure looks like this: ```json {
        "isActive": false, "intervals": [] } ``` The time ranges needs to be
        sorted by the begin parameter This is valid object ```json { "isActive":
        true, "intervals": [ { "begin": "08:00", "end": "09:00", "footfall":
        "GREEN" }, { "begin": "11:00", "end": "14:00", "footfall": "YELLOW" } ]
        } ``` This is an invalid object ```json { "isActive": true, "intervals":
        [ { "begin": "11:00", "end": "14:00", "footfall": "YELLOW" }, { "begin":
        "08:00", "end": "09:00", "footfall": "GREEN" } ] } ```
      operationId: putV1CompaniesByIdSettings
      responses:
        '200':
          description: >-
            Updates company settings and returns the updated settings
            configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Settings updated
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      timezone: America/New_York
                      dateFormat: DD/MM/YYYY
                      timeFormat: HH:mm
                      bookingNotifications: true
                      taxRate: 8.5
                      currency: USD
                      supportEmail: support@salon.com
                      supportPhone: +1-555-0123
                      footfall:
                        sunday:
                          isActive: false
                          intervals: []
                        monday:
                          isActive: true
                          intervals:
                            - begin: '09:00'
                              end: '12:00'
                              footfall: GREEN
                            - begin: '12:00'
                              end: '15:00'
                              footfall: YELLOW
                            - begin: '15:00'
                              end: '18:00'
                              footfall: YELLOW
                        tuesday:
                          isActive: true
                          intervals:
                            - begin: '09:00'
                              end: '12:00'
                              footfall: GREEN
                            - begin: '12:00'
                              end: '15:00'
                              footfall: YELLOW
                            - begin: '15:00'
                              end: '18:00'
                              footfall: YELLOW
                        wednesday:
                          isActive: true
                          intervals:
                            - begin: '09:00'
                              end: '12:00'
                              footfall: GREEN
                            - begin: '12:00'
                              end: '15:00'
                              footfall: YELLOW
                            - begin: '15:00'
                              end: '18:00'
                              footfall: YELLOW
                        thursday:
                          isActive: true
                          intervals:
                            - begin: '09:00'
                              end: '12:00'
                              footfall: GREEN
                            - begin: '12:00'
                              end: '15:00'
                              footfall: YELLOW
                            - begin: '15:00'
                              end: '18:00'
                              footfall: YELLOW
                        friday:
                          isActive: true
                          intervals:
                            - begin: '09:00'
                              end: '12:00'
                              footfall: GREEN
                            - begin: '12:00'
                              end: '17:00'
                              footfall: YELLOW
                            - begin: '17:00'
                              end: '20:00'
                              footfall: ORANGE
                        saturday:
                          isActive: true
                          intervals:
                            - begin: '10:00'
                              end: '14:00'
                              footfall: GREEN
                            - begin: '14:00'
                              end: '19:00'
                              footfall: YELLOW
                      updatedAt: '2024-03-07T14:22:15Z'
                      ts: 1709823735
                    status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: id
          in: path
          required: true
          description: Id path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PutV1CompaniesByIdSettingsRequest'
      security:
        - BearerAuth: []
  /v1/customers:
    get:
      tags:
        - Customers
      summary: List customers
      description: List all customers
      operationId: getV1Customers
      responses:
        '200':
          description: >-
            Returns paginated list of customers with filtering, sorting, and
            pagination applied.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Customer'
                  total:
                    type: integer
                    example: 47
                  meta:
                    $ref: '#/components/schemas/ApiMeta'
                  status:
                    type: integer
                    example: 1
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34cd
                    externalId: CUST-001
                    globalId: internal-cust-001
                    firstName: John
                    lastName: Doe
                    fullName: John Doe
                    companyName: ACME Corp
                    email: john.doe@example.com
                    phone:
                      phone: '+12025551234'
                      number: '2025551234'
                      code: US
                    tags:
                      - id: 65f4c840b6f1a10012ab34ce
                        name: VIP CUSTOMER
                      - id: 65f4c840b6f1a10012ab34cf
                        name: Premium Member
                    tagIds:
                      - 65f4c840b6f1a10012ab34ce
                      - 65f4c840b6f1a10012ab34cf
                    totalBookings: 12
                    avatarUrl: https://api.timify.com/avatars/cust-123.jpg
                    firstLetters:
                      - J
                      - D
                    fields:
                      - id: 65f4c840b6f1a10012ab34d0
                        type: TEXT
                        label: Company
                        value: ACME Corp
                        isMultiple: false
                    createdAt: '2024-01-15T10:30:00Z'
                    updatedAt: '2024-02-20T14:45:30Z'
                    ts: 1708430730
                  - id: 65f4c840b6f1a10012ab34d1
                    externalId: CUST-002
                    globalId: internal-cust-002
                    firstName: Jane
                    lastName: Smith
                    fullName: Jane Smith
                    companyName: Tech Solutions Inc
                    email: jane.smith@example.com
                    phone:
                      phone: '+12025559876'
                      number: '2025559876'
                      code: US
                    tags:
                      - id: 65f4c840b6f1a10012ab34d2
                        name: Regular Customer
                    tagIds:
                      - 65f4c840b6f1a10012ab34d2
                    totalBookings: 3
                    avatarUrl: null
                    firstLetters:
                      - J
                      - S
                    fields:
                      - id: 65f4c840b6f1a10012ab34d0
                        type: TEXT
                        label: Company
                        value: Tech Solutions Inc
                        isMultiple: false
                    createdAt: '2024-02-01T09:15:00Z'
                    updatedAt: '2024-02-25T16:30:00Z'
                    ts: 1708951200
                total: 47
                meta:
                  page: 1
                  limit: 20
                  totalItems: 47
                  totalPages: 3
                status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: >-
            Filter results by customer IDs. Accepts array of valid MongoDB
            ObjectIds.
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: tag_ids
          in: query
          required: false
          description: Filter results by tag IDs. Accepts array of valid MongoDB ObjectIds.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: external_ids
          in: query
          required: false
          description: >-
            Filter results by external customer IDs. Accepts array of external
            ID strings.
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: first_name_letter
          in: query
          required: false
          description: >-
            Filter results by customer first name initial. Accepts single letter
            (A-Z).
          schema:
            type: string
        - name: last_name_letter
          in: query
          required: false
          description: >-
            Filter results by customer last name initial. Accepts single letter
            (A-Z).
          schema:
            type: string
        - name: q
          in: query
          required: false
          description: >-
            Search customers by name or email. Performs text search on customer
            records.
          schema:
            type: string
        - name: booker_id
          in: query
          required: false
          description: Filter results by booker ID. Accepts valid MongoDB ObjectId.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: fields
          in: query
          required: false
          description: >-
            Filter by custom field values. Pass array of {id, type, value}
            objects where id is valid MongoDB ObjectId.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: updated_since
          in: query
          required: false
          description: >-
            Filter results by update date. Returns customers updated since the
            given datetime. Format: ISO 8601 (e.g., 2026-03-02T09:30:00Z).
          schema:
            type: string
            format: date-time
          example: '2026-03-02T09:30:00Z'
        - name: sort_type
          in: query
          required: false
          description: >-
            Sort order direction. Accepts "asc" (ascending) or "desc"
            (descending). Default: asc.
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: sort
          in: query
          required: false
          description: >-
            Sort results by field. Accepts "name", "totalBookings", or
            "createdAt". Default: name.
          schema:
            type: string
            enum:
              - name
              - totalBookings
              - createdAt
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Customers
      summary: Create customer
      description: >-
        The customer data must be added through the payload attribute
        "customfields". Each kind of data associated with a customer is a custom
        filed. For example: firstName, lastName, email etc. You can use the
        endpoint *GET /customers/customfields to retrieve all available custom
        fields for the selected company*. To create a new custom field you can
        use the endpoint *POST customers/customfields*
      operationId: postV1Customers
      responses:
        '201':
          description: Creates new customer and returns created record with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: CUST-001
                  globalId: internal-cust-001
                  firstName: John
                  lastName: Doe
                  fullName: John Doe
                  companyName: ACME Corp
                  email: john.doe@example.com
                  phone:
                    phone: '+12025551234'
                    number: '2025551234'
                    code: US
                  tags: []
                  tagIds: []
                  totalBookings: 0
                  avatarUrl: null
                  firstLetters: JD
                  fields:
                    - id: 65f4c840b6f1a10012ab34d0
                      type: TEXT
                      label: Company
                      value: ACME Corp
                      isMultiple: false
                  createdAt: '2024-03-01T10:30:00Z'
                  updatedAt: '2024-03-01T10:30:00Z'
                  ts: 1709283000
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1CustomersRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/customers/customfields:
    get:
      tags:
        - Customers
      summary: List custom fields
      description: List custom field definitions for customer records.
      operationId: getV1CustomersCustomfields
      responses:
        '200':
          description: >-
            Returns paginated list of custom field definitions available for
            customer records.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: 'Filter or option: ids.'
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: is_mandatory_online
          in: query
          required: false
          description: 'Filter or option: is mandatory online.'
          schema:
            type: boolean
          example: true
        - name: is_mandatory_offline
          in: query
          required: false
          description: 'Filter or option: is mandatory offline.'
          schema:
            type: boolean
          example: true
        - name: is_default
          in: query
          required: false
          description: 'Filter or option: is default.'
          schema:
            type: boolean
          example: true
        - name: type
          in: query
          required: false
          description: 'Filter or option: type.'
          schema:
            type: string
          example: active
        - name: is_published
          in: query
          required: false
          description: 'Filter or option: is published.'
          schema:
            type: boolean
          example: true
        - name: category_id
          in: query
          required: false
          description: 'Filter or option: category id.'
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: has_overwrite
          in: query
          required: false
          description: 'Filter or option: has overwrite.'
          schema:
            type: boolean
          example: true
        - name: is_active
          in: query
          required: false
          description: 'Filter or option: is active.'
          schema:
            type: boolean
          example: true
        - name: services_ids
          in: query
          required: false
          description: 'Filter or option: services ids.'
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: courses_ids
          in: query
          required: false
          description: 'Filter or option: courses ids.'
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Customers
      summary: Add custom field
      description: All new custom fields are available to all customers.
      operationId: postV1CustomersCustomfields
      responses:
        '201':
          description: >-
            Creates new custom field definition and returns created record with
            assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1CustomersCustomfieldsRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/customers/customfields/categories:
    get:
      tags:
        - Customers
      summary: List custom fields categories
      description: List categories that group customer custom fields.
      operationId: getV1CustomersCustomfieldsCategories
      responses:
        '200':
          description: >-
            Returns paginated list of custom field categories for organizing
            customer record fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: 'Filter or option: ids.'
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: is_default
          in: query
          required: false
          description: 'Filter or option: is default.'
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Customers
      summary: Create custom fields category
      description: Create a new custom field category.
      operationId: postV1CustomersCustomfieldsCategories
      responses:
        '201':
          description: >-
            Creates new custom field category and returns created record with
            assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PostV1CustomersCustomfieldsCategoriesRequest
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/customers/customfields/categories/{categoryId}:
    delete:
      tags:
        - Customers
      summary: Delete custom field category
      description: Delete a custom field category.
      operationId: deleteV1CustomersCustomfieldsCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Confirms deletion of the custom field category and returns
            confirmation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Customers
      summary: Fetch custom field category
      description: Fetch a single custom field category.
      operationId: getV1CustomersCustomfieldsCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Returns the specified custom field category with its ID and
            metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Customers
      summary: Update custom fields category
      description: Update a custom field category.
      operationId: patchV1CustomersCustomfieldsCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Updates the custom field category and returns the updated category
            record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PatchV1CustomersCustomfieldsCategoriesByCategoryidRequest
      security:
        - BearerAuth: []
  /v1/customers/customfields/{fieldId}:
    delete:
      tags:
        - Customers
      summary: Delete resource
      description: Delete a custom field definition.
      operationId: deleteV1CustomersCustomfieldsByFieldid
      responses:
        '200':
          description: >-
            Confirms deletion of the custom field definition and returns
            confirmation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: fieldId
          in: path
          required: true
          description: Fieldid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Customers
      summary: Get resource
      description: Fetch a single custom field definition.
      operationId: getV1CustomersCustomfieldsByFieldid
      responses:
        '200':
          description: >-
            Returns the specified custom field definition with its type and
            configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: fieldId
          in: path
          required: true
          description: Fieldid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Customers
      summary: Update custom fields
      description: >-
        Each custom field is a data field for every customer. For example:
        firstName, lastName etc. With this endpoint, you can create your own
        custom fields like customerNr.
      operationId: patchV1CustomersCustomfieldsByFieldid
      responses:
        '200':
          description: >-
            Updates the custom field definition and returns the updated field
            record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: fieldId
          in: path
          required: true
          description: Fieldid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PatchV1CustomersCustomfieldsByFieldidRequest
      security:
        - BearerAuth: []
  /v1/customers/global/{customerId}/events:
    get:
      tags:
        - Customers
      summary: List global customer events
      description: List global customer events
      operationId: getV1CustomersGlobalByCustomeridEvents
      responses:
        '200':
          description: >-
            Returns paginated list of global customer events with region
            filtering applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: customerId
          in: path
          required: true
          description: Customerid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - name: region
          in: query
          required: false
          description: 'Filter or option: region.'
          schema:
            type: string
          example: active
        - name: customer_filter_type
          in: query
          required: false
          description: 'Filter or option: customer filter type.'
          schema:
            type: string
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: with_full_attributes
          in: query
          required: false
          description: 'Filter or option: with full attributes.'
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/customers/import:
    post:
      tags:
        - Customers
      summary: Import or update customers
      description: >-
        Bulk create or update of customers. This endpoint accepts
        *importCustomerId* as a unique identifier for the customer. If there is
        a customer with the *importCustomerId* or *id* then the customer is
        updated.
      operationId: postV1CustomersImport
      responses:
        '201':
          description: >-
            Bulk imports or updates customers and returns import result with
            success/error status for each record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1CustomersImportRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/customers/{customerId}:
    delete:
      tags:
        - Customers
      summary: Delete customer by ID
      description: Delete a customer with the "customerId" or "externalId" parameter
      operationId: deleteV1CustomersByCustomerid
      responses:
        '200':
          description: >-
            Confirms deletion of the customer and returns the deleted customer
            record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: customerId
          in: path
          required: true
          description: Customerid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Customers
      summary: Fetch customer
      description: >-
        The URL parameter "customerId" can be used in two ways: - Unique ID of
        the customer assigned by TIMIFY ("customerId"). In this case, you don't
        need the QUERY parameter "external" - use the "externalId" that you
        added to this customer. In this case, you need to add the parameter
        "external" ( for ex.: */?external=1*) so the api will search by your
        "externalId" and not by "customerId" assigned by TIMIFY You can add
        "externalId" to the customer with the endpoints *POST /customers* and
        *PATCH customers/:customerId*
      operationId: getV1CustomersByCustomerid
      responses:
        '200':
          description: >-
            Returns the specified customer record with complete profile details
            including tags and custom fields.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/Customer'
                  status:
                    type: integer
                    example: 1
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: CUST-001
                  globalId: internal-cust-001
                  firstName: John
                  lastName: Doe
                  fullName: John Doe
                  companyName: ACME Corp
                  email: john.doe@example.com
                  phone:
                    phone: '+12025551234'
                    number: '2025551234'
                    code: US
                  tags:
                    - id: 65f4c840b6f1a10012ab34ce
                      name: VIP CUSTOMER
                    - id: 65f4c840b6f1a10012ab34cf
                      name: Premium Member
                  tagIds:
                    - 65f4c840b6f1a10012ab34ce
                    - 65f4c840b6f1a10012ab34cf
                  totalBookings: 12
                  avatarUrl: https://api.timify.com/avatars/cust-123.jpg
                  firstLetters:
                    - J
                    - D
                  fields:
                    - id: 62ee11aa1d66269c365407c2
                      type: TEXT
                      label: Company
                      value: ACME Corp
                      isMultiple: false
                    - id: 62ee11aa1d66269c365407c3
                      type: EMAIL
                      label: Work Email
                      value: john@acme.com
                      isMultiple: false
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: '2024-02-20T14:45:30Z'
                  ts: 1708430730
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: customerId
          in: path
          required: true
          description: Customerid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Customers
      summary: Update customer
      description: >-
        Update the data of a customer. Customer data is created and updated with
        the "customfield" attribute. Every data attribute of a customer is a
        custom field, for example firstName, lastName, email etc. The URL
        parameter "customerId" can be used in two ways: - As a unique ID of the
        customer assigned by TIMIFY ("customerId"). In this case, you don't need
        the QUERY parameter "external" - use the "externalId" that you added to
        this customer. In this case, you need to add the parameter "external" (
        for ex.: /?external=1) the API will search by your "externalId" and not
        by "customerId" assigned by TIMIFY You can add "externalId" to the
        customer with the Developer API endpoints *POST /customers* and *PATCH
        /customers/:customerId* You can use the endpoint *GET
        /customers/customfields* to retrieve all available custom fields for the
        selected company. To create a new custom field you can use the endpoint
        *POST /customers/customfields*
      operationId: patchV1CustomersByCustomerid
      responses:
        '200':
          description: >-
            Updates the customer record and returns the updated customer with
            all profile details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: CUST-001
                  globalId: internal-cust-001
                  firstName: John
                  lastName: Doe
                  fullName: John Doe
                  companyName: ACME Corp Updated
                  email: john.doe@example.com
                  phone:
                    phone: '+12025551234'
                    number: '2025551234'
                    code: US
                  tags:
                    - id: 65f4c840b6f1a10012ab34ce
                      name: VIP CUSTOMER
                    - id: 65f4c840b6f1a10012ab34d2
                      name: Regular Customer
                  tagIds:
                    - 65f4c840b6f1a10012ab34ce
                    - 65f4c840b6f1a10012ab34d2
                  totalBookings: 12
                  avatarUrl: https://api.timify.com/avatars/cust-123.jpg
                  firstLetters: JD
                  fields:
                    - id: 62ee11aa1d66269c365407c2
                      type: TEXT
                      label: Company
                      value: ACME Corp Updated
                      isMultiple: false
                    - id: 62ee11aa1d66269c365407c3
                      type: EMAIL
                      label: Work Email
                      value: john@acme.com
                      isMultiple: false
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: '2024-03-01T15:20:00Z'
                  ts: 1709297400
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: customerId
          in: path
          required: true
          description: Customerid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1CustomersByCustomeridRequest'
      security:
        - BearerAuth: []
  /v1/enterprise-customers:
    get:
      tags:
        - Enterprise Customers
      summary: List enterprise customers
      description: List of all or filtered customers defined at the enterprise level
      operationId: getV1EnterpriseCustomers
      responses:
        '200':
          description: >-
            Returns paginated list of enterprise-level customers with filtering,
            sorting, and pagination applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: 'Filter or option: ids.'
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: tag_ids
          in: query
          required: false
          description: 'Filter or option: tag ids.'
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: external_ids
          in: query
          required: false
          description: 'Filter or option: external ids.'
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: first_name_letter
          in: query
          required: false
          description: 'Filter or option: first name letter.'
          schema:
            type: string
        - name: last_name_letter
          in: query
          required: false
          description: 'Filter or option: last name letter.'
          schema:
            type: string
        - name: q
          in: query
          required: false
          description: 'Filter or option: q.'
          schema:
            type: string
        - name: booker_id
          in: query
          required: false
          description: 'Filter or option: booker id.'
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: fields
          in: query
          required: false
          description: 'Filter or option: fields.'
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: updated_since
          in: query
          required: false
          description: 'Filter or option: updated since.'
          schema:
            type: string
            format: date
          example: '2026-03-02'
        - name: sort_type
          in: query
          required: false
          description: 'Filter or option: sort type.'
          schema:
            type: string
        - name: sort
          in: query
          required: false
          description: 'Filter or option: sort.'
          schema:
            type: string
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Enterprise Customers
      summary: Create enterprise customer
      description: >-
        The customer will be available in all branches. The customer data must
        be added through the payload attribute "customfields". Each kind of data
        associated with a customer is a custom filed. For example: firstName,
        lastName, email etc. You can use the endpoint *GET
        /customers/customfields to retrieve all available custom fields for the
        selected company*. To create a new custom field you can use the endpoint
        *POST customers/customfields*
      operationId: postV1EnterpriseCustomers
      responses:
        '201':
          description: >-
            Creates new enterprise-level customer and returns created record
            with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1EnterpriseCustomersRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprise-customers/customfields:
    get:
      tags:
        - Enterprise Customers
      summary: List enterprise custom fields
      description: List custom field definitions for enterprise customers.
      operationId: getV1EnterpriseCustomersCustomfields
      responses:
        '200':
          description: >-
            Returns paginated list of custom field definitions for enterprise
            customers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: 'Filter or option: ids.'
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: external_ids
          in: query
          required: false
          description: 'Filter or option: external ids.'
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: is_mandatory_online
          in: query
          required: false
          description: 'Filter or option: is mandatory online.'
          schema:
            type: boolean
          example: true
        - name: is_mandatory_offline
          in: query
          required: false
          description: 'Filter or option: is mandatory offline.'
          schema:
            type: boolean
          example: true
        - name: is_default
          in: query
          required: false
          description: 'Filter or option: is default.'
          schema:
            type: boolean
          example: true
        - name: type
          in: query
          required: false
          description: 'Filter or option: type.'
          schema:
            type: string
          example: active
        - name: is_published
          in: query
          required: false
          description: 'Filter or option: is published.'
          schema:
            type: boolean
          example: true
        - name: category_id
          in: query
          required: false
          description: 'Filter or option: category id.'
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: has_overwrite
          in: query
          required: false
          description: 'Filter or option: has overwrite.'
          schema:
            type: boolean
          example: true
        - name: is_active
          in: query
          required: false
          description: 'Filter or option: is active.'
          schema:
            type: boolean
          example: true
        - name: services_ids
          in: query
          required: false
          description: 'Filter or option: services ids.'
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: courses_ids
          in: query
          required: false
          description: 'Filter or option: courses ids.'
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: internal_id
          in: query
          required: false
          description: 'Filter or option: internal id.'
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: only_locals
          in: query
          required: false
          description: 'Filter or option: only locals.'
          schema:
            type: string
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Enterprise Customers
      summary: Create enterprise custom field
      description: All new custom fields are available to all customers.
      operationId: postV1EnterpriseCustomersCustomfields
      responses:
        '201':
          description: >-
            Creates new enterprise custom field definition and returns created
            field record with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PostV1EnterpriseCustomersCustomfieldsRequest
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprise-customers/customfields/categories:
    get:
      tags:
        - Enterprise Customers
      summary: List enterprise custom field categories
      description: List categories that group enterprise customer custom fields.
      operationId: getV1EnterpriseCustomersCustomfieldsCategories
      responses:
        '200':
          description: >-
            Returns paginated list of enterprise custom field categories that
            group custom field definitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: 'Filter or option: ids.'
          schema:
            type: array
            items:
              type: string
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: is_default
          in: query
          required: false
          description: 'Filter or option: is default.'
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Enterprise Customers
      summary: Create enterprise custom fields category
      description: Create a custom field category for enterprise customers.
      operationId: postV1EnterpriseCustomersCustomfieldsCategories
      responses:
        '201':
          description: >-
            Creates new enterprise custom field category and returns created
            category record with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PostV1EnterpriseCustomersCustomfieldsCategoriesRequest
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprise-customers/customfields/categories/{categoryId}:
    delete:
      tags:
        - Enterprise Customers
      summary: Delete enterprise custom fields category
      description: Delete an enterprise customer custom field category.
      operationId: deleteV1EnterpriseCustomersCustomfieldsCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Confirms deletion of the enterprise custom field category and
            returns confirmation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Enterprise Customers
      summary: Fetch enterprise custom field category
      description: Fetch a single enterprise customer custom field category.
      operationId: getV1EnterpriseCustomersCustomfieldsCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Returns the specified enterprise custom field category with its
            metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Enterprise Customers
      summary: Update enterprise custom fields category
      description: Update an enterprise customer custom field category.
      operationId: patchV1EnterpriseCustomersCustomfieldsCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Updates the enterprise custom field category and returns the updated
            category record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PatchV1EnterpriseCustomersCustomfieldsCategoriesByCategoryidRequest
      security:
        - BearerAuth: []
  /v1/enterprise-customers/customfields/{fieldId}:
    delete:
      tags:
        - Enterprise Customers
      summary: Delete enterprise custom field
      description: Delete an enterprise customer custom field definition.
      operationId: deleteV1EnterpriseCustomersCustomfieldsByFieldid
      responses:
        '200':
          description: >-
            Confirms deletion of the enterprise custom field definition and
            returns confirmation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: fieldId
          in: path
          required: true
          description: Fieldid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Enterprise Customers
      summary: Fetch enterprise customer field
      description: Fetch a single enterprise customer custom field definition.
      operationId: getV1EnterpriseCustomersCustomfieldsByFieldid
      responses:
        '200':
          description: >-
            Returns the specified enterprise custom field definition with its
            type and configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: fieldId
          in: path
          required: true
          description: Fieldid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Enterprise Customers
      summary: Update enterprise custom field
      description: >-
        Each custom field is a data field for every customer. For example:
        firstName, lastName etc. With this endpoint, you can create your own
        custom fields like customerNr.
      operationId: patchV1EnterpriseCustomersCustomfieldsByFieldid
      responses:
        '200':
          description: >-
            Updates the enterprise custom field definition and returns the
            updated field record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: fieldId
          in: path
          required: true
          description: Fieldid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PatchV1EnterpriseCustomersCustomfieldsByFieldidRequest
      security:
        - BearerAuth: []
  /v1/enterprise-customers/import:
    post:
      tags:
        - Enterprise Customers
      summary: Post import
      description: Bulk import or update enterprise customers.
      operationId: postV1EnterpriseCustomersImport
      responses:
        '201':
          description: >-
            Bulk imports or updates enterprise customers and returns import
            result with success/error status for each record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1EnterpriseCustomersImportRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprise-customers/{customerId}:
    delete:
      tags:
        - Enterprise Customers
      summary: Delete enterprise customer
      description: Delete a customer with the "customerId" or "externalId" parameter
      operationId: deleteV1EnterpriseCustomersByCustomerid
      responses:
        '200':
          description: >-
            Confirms deletion of the enterprise customer and returns the deleted
            customer record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: customerId
          in: path
          required: true
          description: Customerid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Enterprise Customers
      summary: Fetch enterprise customer
      description: >-
        The URL parameter "customerId" can be used in two ways: - Unique ID of
        the customer assigned by TIMIFY ("customerId"). In this case, you don't
        need the QUERY parameter "external" - use the "externalId" that you
        added to this customer. In this case, you need to add the parameter
        "external" ( for ex.: */?external=1*) so the api will search by your
        "externalId" and not by "customerId" assigned by TIMIFY You can add
        "externalId" to the customer with the endpoints *POST /customers* and
        *PATCH customers/:customerId*
      operationId: getV1EnterpriseCustomersByCustomerid
      responses:
        '200':
          description: >-
            Returns the specified enterprise customer record with complete
            profile details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: customerId
          in: path
          required: true
          description: Customerid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Enterprise Customers
      summary: Update enterprise customer
      description: >-
        Update the data of a customer. Customer data is created and updated with
        the "customfield" attribute. Every data attribute of a customer is a
        custom field, for example firstName, lastName, email etc. The URL
        parameter "customerId" can be used in two ways: - As a unique ID of the
        customer assigned by TIMIFY ("customerId"). In this case, you don't need
        the QUERY parameter "external" - use the "externalId" that you added to
        this customer. In this case, you need to add the parameter "external" (
        for ex.: /?external=1) the API will search by your "externalId" and not
        by "customerId" assigned by TIMIFY You can add "externalId" to the
        customer with the Developer API endpoints *POST /customers* and *PATCH
        /customers/:customerId* You can use the endpoint *GET
        /customers/customfields* to retrieve all available custom fields for the
        selected company. To create a new custom field you can use the endpoint
        *POST /customers/customfields*
      operationId: patchV1EnterpriseCustomersByCustomerid
      responses:
        '200':
          description: >-
            Updates the enterprise customer record and returns the updated
            customer with all profile details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: customerId
          in: path
          required: true
          description: Customerid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PatchV1EnterpriseCustomersByCustomeridRequest
      security:
        - BearerAuth: []
  /v1/enterprise-customers/{customerId}/events:
    get:
      tags:
        - Enterprise Customers
      summary: List customer events
      description: List customer events
      operationId: getV1EnterpriseCustomersByCustomeridEvents
      responses:
        '200':
          description: >-
            Returns paginated list of events for the specified enterprise
            customer.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: customerId
          in: path
          required: true
          description: Customerid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - name: customer_filter_type
          in: query
          required: false
          description: 'Filter or option: customer filter type.'
          schema:
            type: string
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: with_full_attributes
          in: query
          required: false
          description: 'Filter or option: with full attributes.'
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/enterprise-managers:
    get:
      tags:
        - Enterprises
      summary: List enterprise Managers
      description: List managers (admin users) for the enterprise.
      operationId: getV1EnterpriseManagers
      responses:
        '200':
          description: >-
            Returns paginated list of enterprise managers with their access
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34d7
                    firstName: Alice
                    lastName: Johnson
                    email: alice.johnson@example.com
                    role: ADMIN
                    isActive: true
                    scope: enterprise
                    permissions:
                      - manage_companies
                      - manage_users
                      - view_analytics
                    createdAt: '2025-01-15T10:00:00Z'
                    updatedAt: '2026-03-01T14:30:00Z'
                    ts: 1709305800
                  - id: 65f4c840b6f1a10012ab34d8
                    firstName: Bob
                    lastName: Smith
                    email: bob.smith@example.com
                    role: MANAGER
                    isActive: true
                    scope: enterprise
                    permissions:
                      - manage_companies
                      - view_analytics
                    createdAt: '2025-02-10T09:15:00Z'
                    updatedAt: '2026-02-28T11:45:00Z'
                    ts: 1709218500
                total: 2
                meta:
                  page: 1
                  limit: 20
                  totalItems: 2
                  totalPages: 1
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/enterprise-managers/{managerId}:
    get:
      tags:
        - Enterprises
      summary: Fetch enterprise manager
      description: Fetch a single enterprise manager by their ID.
      operationId: getV1EnterpriseManagersByManagerid
      responses:
        '200':
          description: Returns the specified enterprise manager with their profile details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34d7
                  firstName: Alice
                  lastName: Johnson
                  email: alice.johnson@example.com
                  role: ADMIN
                  isActive: true
                  scope: enterprise
                  permissions:
                    - manage_companies
                    - manage_users
                    - view_analytics
                    - manage_settings
                    - manage_billing
                  createdAt: '2025-01-15T10:00:00Z'
                  updatedAt: '2026-03-01T14:30:00Z'
                  ts: 1709305800
                  companiesCount: 5
                  lastLoginAt: '2026-03-06T16:20:00Z'
                status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: managerId
          in: path
          required: true
          description: Managerid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/enterprises:
    get:
      tags:
        - Enterprises
      summary: Fetch an enterprise
      description: Return the enterprise(s) accessible to the authenticated token.
      operationId: getV1Enterprises
      responses:
        '200':
          description: >-
            Returns paginated list of accessible enterprises with account
            metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - id: 55f4c840b6f1a10012ab34cd
                    slug: acme-enterprise
                    name: ACME Enterprise
                    externalId: EXT-ENT-001
                    description: Multi-location scheduling platform
                    defaultBrandColor: '#0066cc'
                    isActive: true
                    status: active
                    plan: PREMIUM
                    companiesCount: 5
                    managersCount: 2
                    createdAt: '2024-01-01T08:00:00Z'
                    updatedAt: '2026-03-01T12:00:00Z'
                    ts: 1709295600
                    features:
                      multiLocation: true
                      customBranding: true
                      apiAccess: true
                      advancedAnalytics: true
                total: 1
                meta:
                  page: 1
                  limit: 20
                  totalItems: 1
                  totalPages: 1
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/enterprises-companies:
    get:
      tags:
        - Enterprises
      summary: Get enterprises companies
      description: List all companies that belong to the enterprise.
      operationId: getV1EnterprisesCompanies
      responses:
        '200':
          description: >-
            Returns paginated list of companies within the enterprise with their
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34d9
                    slug: acme-head-office
                    name: ACME Head Office
                    externalId: EXT-CO-001
                    description: Main headquarters location
                    isActive: true
                    status: active
                    city: New York
                    state: NY
                    country: United States
                    timezone: America/New_York
                    onlineBookingEnabled: true
                    createdAt: '2024-02-01T10:00:00Z'
                    updatedAt: '2026-03-05T14:30:00Z'
                    ts: 1709218200
                  - id: 65f4c840b6f1a10012ab34da
                    slug: acme-branch-la
                    name: ACME LA Branch
                    externalId: EXT-CO-002
                    description: Los Angeles branch office
                    isActive: true
                    status: active
                    city: Los Angeles
                    state: CA
                    country: United States
                    timezone: America/Los_Angeles
                    onlineBookingEnabled: true
                    createdAt: '2024-03-15T09:30:00Z'
                    updatedAt: '2026-03-04T11:15:00Z'
                    ts: 1709131500
                total: 2
                meta:
                  page: 1
                  limit: 20
                  totalItems: 2
                  totalPages: 1
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: fields
          in: query
          required: false
          description: >-
            Select which company fields to include in the response
            (comma-separated list).
          schema:
            type: array
            items:
              type: string
              example: name
            minItems: 1
          example:
            - name
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Enterprises
      summary: Create enterprise branch
      description: Add a new company under the enterprise.
      operationId: postV1EnterprisesCompanies
      responses:
        '201':
          description: >-
            Creates new company branch under the enterprise and returns created
            record with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34db
                  slug: acme-branch-chicago
                  name: ACME Chicago Branch
                  externalId: EXT-CO-003
                  description: Chicago regional office
                  isActive: true
                  status: active
                  city: Chicago
                  state: IL
                  country: United States
                  timezone: America/Chicago
                  onlineBookingEnabled: true
                  createdAt: '2026-03-07T15:45:00Z'
                  updatedAt: '2026-03-07T15:45:00Z'
                  ts: 1709864700
                  apiKey: ABC123XYZ789
                  apiSecret: secret_5e8f3c2b1a9d4f6e
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1EnterprisesCompaniesRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprises-companies/cancel/{companyId}:
    put:
      tags:
        - Enterprises
      summary: Cancel enterprise company
      description: Cancel the subscription for an enterprise-managed company.
      operationId: putV1EnterprisesCompaniesCancelByCompanyid
      responses:
        '200':
          description: >-
            Cancels the subscription for the enterprise company and returns
            cancellation confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34d9
                  name: ACME Head Office
                  status: cancelled
                  cancelledAt: '2026-03-07T16:20:00Z'
                  cancelledBy: 65f4c840b6f1a10012ab34d7
                  cancellationReason: Consolidation with other branch
                  effectiveDate: '2026-04-30T23:59:59Z'
                  dataRetentionUntil: '2026-09-07T23:59:59Z'
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: companyId
          in: path
          required: true
          description: Companyid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/enterprises-companies/delete-queue:
    get:
      tags:
        - Enterprises
      summary: Get delete queue
      description: List enterprise companies queued for deletion.
      operationId: getV1EnterprisesCompaniesDeleteQueue
      responses:
        '200':
          description: >-
            Returns companies queued for deletion with their pending deletion
            status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  companies:
                    - id: 65f4c840b6f1a10012ab34d9
                      name: ACME Head Office
                      status: pending_deletion
                      scheduledForDeletionAt: '2026-04-07T00:00:00Z'
                      requestedBy: alice.johnson@example.com
                      requestedAt: '2026-03-07T16:20:00Z'
                      reason: Consolidation
                    - id: 65f4c840b6f1a10012ab34da
                      name: ACME LA Branch
                      status: pending_deletion
                      scheduledForDeletionAt: '2026-04-14T00:00:00Z'
                      requestedBy: bob.smith@example.com
                      requestedAt: '2026-03-06T10:15:00Z'
                      reason: Location closure
                  totalPending: 2
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: company_ids
          in: query
          required: false
          description: >-
            Filter deletion queue by specific company IDs. Comma-separated list
            of valid MongoDB IDs.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/enterprises-companies/delete/bulk:
    post:
      tags:
        - Enterprises
      summary: Bulk delete enterprise companies
      description: >-
        Delete multiple enterprise-managed companies by their IDs in a single
        request.
      operationId: postV1EnterprisesCompaniesDeleteBulk
      responses:
        '201':
          description: >-
            Bulk deletes enterprise companies and returns deletion result with
            status for each record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  deleted:
                    - id: 65f4c840b6f1a10012ab34d9
                      name: ACME Head Office
                      status: deleted
                      deletedAt: '2026-03-07T17:00:00Z'
                    - id: 65f4c840b6f1a10012ab34da
                      name: ACME LA Branch
                      status: deleted
                      deletedAt: '2026-03-07T17:00:00Z'
                  failed:
                    - id: 65f4c840b6f1a10012ab34db
                      name: ACME Chicago Branch
                      status: failed
                      reason: Company has active bookings
                  deletedCount: 2
                  failedCount: 1
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1EnterprisesCompaniesDeleteBulkRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprises-companies/generate-secret:
    post:
      tags:
        - Enterprises
      summary: Generate enterprise company secret
      description: Generate or rotate the API secret for an enterprise-managed company.
      operationId: postV1EnterprisesCompaniesGenerateSecret
      responses:
        '201':
          description: >-
            Generates or rotates the API secret for the enterprise company and
            returns the new secret.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34db
                  name: ACME Chicago Branch
                  apiKey: ABC123XYZ789
                  apiSecret: new_secret_k9m3p7q2w1x8c5v4b
                  generatedAt: '2026-03-07T17:15:00Z'
                  previousSecretRevoked: true
                  revokedAt: '2026-03-07T17:15:00Z'
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PostV1EnterprisesCompaniesGenerateSecretRequest
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprises-companies/{companyId}/onlinestatus:
    put:
      tags:
        - Enterprises
      summary: Toggle online status of the company
      description: >-
        Toggle the online booking status of a specific company within an
        enterprise.
      operationId: putV1EnterprisesCompaniesByCompanyidOnlinestatus
      responses:
        '200':
          description: >-
            Updates the online booking status for the enterprise company and
            returns status confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34db
                  name: ACME Chicago Branch
                  onlineBookingEnabled: false
                  previousStatus: true
                  changedAt: '2026-03-07T17:30:00Z'
                  changedBy: alice.johnson@example.com
                  reason: Scheduled maintenance
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: companyId
          in: path
          required: true
          description: Companyid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PutV1EnterprisesCompaniesByCompanyidOnlinestatusRequest
      security:
        - BearerAuth: []
  /v1/enterprises-companies/{id}:
    get:
      tags:
        - Enterprises
      summary: Get enterprise company
      description: Fetch a single enterprise-managed company by its ID or external ID.
      operationId: getV1EnterprisesCompaniesById
      responses:
        '200':
          description: >-
            Returns the specified enterprise-managed company with its complete
            profile and settings.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34db
                  slug: acme-branch-chicago
                  name: ACME Chicago Branch
                  externalId: EXT-CO-003
                  description: Chicago regional office
                  isActive: true
                  status: active
                  city: Chicago
                  state: IL
                  country: United States
                  zipCode: '60601'
                  timezone: America/Chicago
                  onlineBookingEnabled: false
                  contactName: John Manager
                  contactEmail: john@acme-chicago.example.com
                  contactPhone: +1-312-555-0100
                  createdAt: '2026-03-07T15:45:00Z'
                  updatedAt: '2026-03-07T17:30:00Z'
                  ts: 1709864700
                  apiKey: ABC123XYZ789
                  resourcesCount: 12
                  servicesCount: 8
                  appointmentsCount: 145
                  customersCount: 89
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: id
          in: path
          required: true
          description: Id path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: fields
          in: query
          required: false
          description: >-
            Select which company fields to include in the response
            (comma-separated list).
          schema:
            type: array
            items:
              type: string
              example: name
            minItems: 1
          example:
            - name
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Enterprises
      summary: Update enterprise branch
      description: Update properties of an enterprise-managed company.
      operationId: patchV1EnterprisesCompaniesById
      responses:
        '200':
          description: >-
            Updates properties of the enterprise-managed company and returns the
            updated company record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34db
                  slug: acme-branch-chicago
                  name: ACME Chicago Regional Office
                  externalId: EXT-CO-003
                  description: Chicago regional office - expanded services
                  isActive: true
                  status: active
                  city: Chicago
                  state: IL
                  country: United States
                  zipCode: '60601'
                  timezone: America/Chicago
                  onlineBookingEnabled: true
                  contactName: Jane Manager
                  contactEmail: jane@acme-chicago.example.com
                  contactPhone: +1-312-555-0101
                  createdAt: '2026-03-07T15:45:00Z'
                  updatedAt: '2026-03-07T17:45:00Z'
                  ts: 1709864700
                  resourcesCount: 12
                  servicesCount: 8
                  appointmentsCount: 145
                  customersCount: 89
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: id
          in: path
          required: true
          description: Id path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1EnterprisesCompaniesByIdRequest'
      security:
        - BearerAuth: []
  /v1/enterprises/settings:
    patch:
      tags:
        - Enterprises
      summary: Update settings of an enterprise
      description: Update configuration settings for the enterprise account.
      operationId: patchV1EnterprisesSettings
      responses:
        '200':
          description: >-
            Updates configuration settings for the enterprise and returns the
            updated settings record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 55f4c840b6f1a10012ab34cd
                  name: ACME Enterprise
                  defaultBrandColor: '#0066cc'
                  timezone: America/New_York
                  dateFormat: MM/DD/YYYY
                  timeFormat: 12h
                  bookingNotifications: true
                  appointmentRemindersDays: 1
                  autoConfirmAppointments: false
                  allowCustomerCancellation: true
                  cancellationNoticeHours: 24
                  onlinePricingEnabled: true
                  taxRate: 8.875
                  currency: USD
                  logo: https://cdn.example.com/acme-logo.png
                  supportEmail: support@acme.example.com
                  supportPhone: +1-800-ACME-123
                  updatedAt: '2026-03-07T18:00:00Z'
                  updatedBy: alice.johnson@example.com
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1EnterprisesSettingsRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprises/statistics:
    get:
      tags:
        - Enterprises
      summary: Fetch enterprise statistics
      description: Return aggregate booking and usage statistics for the enterprise.
      operationId: getV1EnterprisesStatistics
      responses:
        '200':
          description: >-
            Returns paginated list of aggregate booking and usage statistics for
            the enterprise with optional filtering by date.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - date: '2026-03-07'
                    period: DAILY
                    totalAppointments: 87
                    completedAppointments: 72
                    cancelledAppointments: 5
                    noShowAppointments: 10
                    totalCustomers: 89
                    newCustomers: 3
                    recurringBookings: 42
                    totalRevenue: 4250.5
                    onlineBookings: 34
                    offlineBookings: 53
                  - date: '2026-03-06'
                    period: DAILY
                    totalAppointments: 92
                    completedAppointments: 78
                    cancelledAppointments: 8
                    noShowAppointments: 6
                    totalCustomers: 86
                    newCustomers: 2
                    recurringBookings: 45
                    totalRevenue: 4320.75
                    onlineBookings: 38
                    offlineBookings: 54
                total: 31
                meta:
                  page: 1
                  limit: 20
                  totalItems: 31
                  totalPages: 2
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: month
          in: query
          required: false
          description: 'Filter statistics by month (format: MM or 1-12).'
          schema:
            type: string
        - name: year
          in: query
          required: false
          description: 'Filter statistics by year (format: YYYY).'
          schema:
            type: string
        - name: statistics_mode
          in: query
          required: false
          description: Statistics aggregation mode (e.g., DAILY, MONTHLY, YEARLY).
          schema:
            type: string
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/enterprise-files:
    post:
      tags:
        - Files
      summary: Download enterprise file
      description: >-
        Download files for a customer or appointment. Import csv files can be
        downloaded for resources/services/categories... The required parameters
        can be found in _GET /customer/{customerId}_ or _GET
        /reservation/{reservationId}_
      operationId: postV1EnterpriseFiles
      responses:
        '201':
          description: >-
            Generates and returns enterprise file for the specified customer or
            appointment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Enterprise file generated
                  value:
                    data:
                      id: 65f6e062d8h3c31234cd56eg
                      fileName: customer-invoice-65f4c840b6f1a10012ab34cd.pdf
                      fileType: application/pdf
                      fileSize: 245832
                      downloadUrl: >-
                        https://api.timify.io/files/65f6e062d8h3c31234cd56eg/download
                      expiresAt: '2024-03-14T16:30:00Z'
                      createdAt: '2024-03-07T16:30:00Z'
                      ts: 1709834400
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1EnterpriseFilesRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/files:
    post:
      tags:
        - Files
      summary: Download file
      description: >-
        Download files for a customer or appointment. The required parameters
        can be found in _GET /customer/{customerId}_ or _GET
        /reservation/{reservationId}_
      operationId: postV1Files
      responses:
        '201':
          description: >-
            Generates and returns file for the specified customer or
            appointment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: File generated
                  value:
                    data:
                      id: 65f7f173e9i4d42345de67fh
                      fileName: appointment-receipt-65f4c840b6f1a10012ab34cd.pdf
                      fileType: application/pdf
                      fileSize: 127456
                      downloadUrl: >-
                        https://api.timify.io/files/65f7f173e9i4d42345de67fh/download
                      expiresAt: '2024-03-14T17:00:00Z'
                      createdAt: '2024-03-07T17:00:00Z'
                      ts: 1709836000
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1FilesRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/group-services:
    get:
      tags:
        - Group Services
      summary: Lists group services
      description: >-
        These are services like courses, workshops or events that are offered
        for more than 1 attendee.
      operationId: getV1GroupServices
      responses:
        '200':
          description: >-
            Returns paginated list of group services (courses, workshops,
            events) with their details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - id: 75f4c840b6f1a10012ab34cd
                    name: Yoga Fundamentals
                    externalId: EXT-GS-001
                    description: 8-week beginner yoga course
                    duration: 60
                    durationBefore: 10
                    durationAfter: 5
                    price: 89.99
                    maxParticipants: 15
                    minParticipants: 5
                    currentParticipants: 12
                    isBookable: true
                    isCourse: true
                    color: '#95c5a6'
                    categoryId: 65f4c840b6f1a10012ab34dc
                    categoryName: Wellness
                    resourceIds:
                      - 62ee11a91d66269c365407b1
                    scheduleType: weekly
                    frequency: WEEKS
                    createdAt: '2025-11-01T10:00:00Z'
                    updatedAt: '2026-03-01T14:30:00Z'
                    ts: 1709305800
                  - id: 75f4c840b6f1a10012ab34ce
                    name: Web Development Workshop
                    externalId: EXT-GS-002
                    description: 4-week intensive JavaScript workshop
                    duration: 120
                    durationBefore: 15
                    durationAfter: 10
                    price: 299.99
                    maxParticipants: 20
                    minParticipants: 8
                    currentParticipants: 16
                    isBookable: true
                    isCourse: true
                    color: '#7684ca'
                    categoryId: 65f4c840b6f1a10012ab34dd
                    categoryName: Technology
                    resourceIds:
                      - 62ee11a91d66269c365407b2
                      - 62ee11a91d66269c365407b3
                    scheduleType: biweekly
                    frequency: WEEKS
                    createdAt: '2025-10-15T09:30:00Z'
                    updatedAt: '2026-02-28T11:15:00Z'
                    ts: 1709218500
                total: 2
                meta:
                  page: 1
                  limit: 20
                  totalItems: 2
                  totalPages: 1
                status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: is_bookable
          in: query
          required: false
          description: Filter group services by bookable status (true or false).
          schema:
            type: boolean
          example: true
        - name: ids
          in: query
          required: false
          description: >-
            Filter group services by IDs. Comma-separated list of valid MongoDB
            IDs.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: resource_category_id
          in: query
          required: false
          description: >-
            Filter group services by resource category ID. Must be a valid
            MongoDB ID.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: resource_id
          in: query
          required: false
          description: Filter group services by resource ID. Must be a valid MongoDB ID.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: category_id
          in: query
          required: false
          description: Filter group services by category ID. Must be a valid MongoDB ID.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: external_ids
          in: query
          required: false
          description: >-
            Filter group services by external IDs. Comma-separated list of
            external identifiers.
          schema:
            type: array
            items:
              type: string
              example: ext-service-001
            minItems: 1
          example:
            - ext-service-001
        - name: is_stalled
          in: query
          required: false
          description: Filter group services by stalled status (true or false).
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: sort_type
          in: query
          required: false
          description: Sort field name (e.g., name, createdAt, updatedAt).
          schema:
            type: string
        - name: sort
          in: query
          required: false
          description: Sort order (asc for ascending, desc for descending).
          schema:
            type: string
        - name: with_full_attributes
          in: query
          required: false
          description: Include full service attributes in the response (true or false).
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Group Services
      summary: Create group service
      description: >-
        Create a new group service (course, workshop, or event). Group services
        support multiple participants and recurring schedules.
      operationId: postV1GroupServices
      responses:
        '201':
          description: >-
            Creates new group service and returns created record with assigned
            ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 75f4c840b6f1a10012ab34cf
                  name: Pilates for Beginners
                  externalId: EXT-GS-003
                  description: 6-week pilates fundamentals course
                  duration: 50
                  durationBefore: 10
                  durationAfter: 5
                  price: 79.99
                  maxParticipants: 12
                  minParticipants: 4
                  currentParticipants: 0
                  isBookable: true
                  isCourse: true
                  color: '#e5774c'
                  categoryId: 65f4c840b6f1a10012ab34dc
                  categoryName: Wellness
                  resourceIds:
                    - 62ee11a91d66269c365407b1
                  scheduleType: weekly
                  frequency: WEEKS
                  createdAt: '2026-03-07T18:30:00Z'
                  updatedAt: '2026-03-07T18:30:00Z'
                  ts: 1709865000
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1GroupServicesRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/group-services/categories:
    get:
      tags:
        - Group Services
      summary: List group service categories
      description: >-
        Returns all group service (course/event) categories for the
        authenticated company.
      operationId: getV1GroupServicesCategories
      responses:
        '200':
          description: >-
            Returns paginated list of group service categories with their
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34dc
                    name: Wellness
                    externalId: EXT-GS-CAT-001
                    description: Health and fitness courses
                    orderIndex: 1
                    isDefault: false
                    createdAt: '2024-06-01T08:00:00Z'
                    updatedAt: '2026-02-15T12:30:00Z'
                    ts: 1707990600
                  - id: 65f4c840b6f1a10012ab34dd
                    name: Technology
                    externalId: EXT-GS-CAT-002
                    description: Programming and IT training courses
                    orderIndex: 2
                    isDefault: false
                    createdAt: '2024-07-10T09:15:00Z'
                    updatedAt: '2026-03-01T10:45:00Z'
                    ts: 1709295900
                total: 2
                meta:
                  page: 1
                  limit: 20
                  totalItems: 2
                  totalPages: 1
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: Filter categories by IDs. Comma-separated list of valid MongoDB IDs.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: resource_id
          in: query
          required: false
          description: Filter categories by resource ID. Must be a valid MongoDB ID.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Group Services
      summary: Create group service category
      description: Create a new category to organize group services.
      operationId: postV1GroupServicesCategories
      responses:
        '201':
          description: >-
            Creates new group service category and returns created record with
            assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34de
                  name: Arts & Crafts
                  externalId: EXT-GS-CAT-003
                  description: Creative and artistic courses
                  orderIndex: 3
                  isDefault: false
                  createdAt: '2026-03-07T19:00:00Z'
                  updatedAt: '2026-03-07T19:00:00Z'
                  ts: 1709865600
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1GroupServicesCategoriesRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/group-services/categories/{categoryId}:
    delete:
      tags:
        - Group Services
      summary: Delete group service category
      description: >-
        The URL parameter "categoryId" can be used in two ways: - use the unique
        ID of the group service category assigned by TIMIFY ("categoryId"). In
        this case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this group service category. In this
        case, you need to add the parameter "external" ( for ex.:
        */?external=1*) so the Developer API will search by your "externalId"
        and not by "categoryId" assigned by TIMIFY You can add "externalId" to
        the group service with the Developer API endpoints *POST
        /group-services/caetgories* and *PATCH
        /group-service/categories/:categoryId*
      operationId: deleteV1GroupServicesCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Confirms deletion of the group service category and returns the
            deleted category record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Group Services
      summary: Fetch service group category
      description: >-
        The URL parameter "categoryId" can be used in two ways: - use the unique
        ID of the group service category assigned by TIMIFY ("categoryId"). In
        this case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this group service category. In this
        case, you need to add the parameter "external" ( for ex.:
        */?external=1*) so the Developer API will search by your "externalId"
        and not by "categoryId" assigned by TIMIFY You can add "externalId" to
        the service category with the Developer API endpoints *POST
        /services/categories* and *PATCH /services/categories/:categoryId*
      operationId: getV1GroupServicesCategoriesByCategoryid
      responses:
        '200':
          description: Returns the specified group service category with its details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34dc
                  name: Wellness
                  externalId: EXT-GS-CAT-001
                  description: Health and fitness courses
                  orderIndex: 1
                  isDefault: false
                  servicesCount: 3
                  createdAt: '2024-06-01T08:00:00Z'
                  updatedAt: '2026-02-15T12:30:00Z'
                  ts: 1707990600
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Group Services
      summary: Update group service category
      description: >-
        Update an existing group service category. Supports externalId lookup
        via `?external=1`.
      operationId: patchV1GroupServicesCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Updates the group service category and returns the updated category
            record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34dc
                  name: Health & Wellness
                  externalId: EXT-GS-CAT-001
                  description: Health, fitness and wellness courses
                  orderIndex: 1
                  isDefault: false
                  servicesCount: 3
                  createdAt: '2024-06-01T08:00:00Z'
                  updatedAt: '2026-03-07T19:15:00Z'
                  ts: 1707990600
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PatchV1GroupServicesCategoriesByCategoryidRequest
      security:
        - BearerAuth: []
  /v1/group-services/{groupServiceId}:
    delete:
      tags:
        - Group Services
      summary: Delete group service
      description: >-
        The URL parameter "serviceId" can be used in two ways: - use the unique
        ID of the service assigned by TIMIFY ("serviceId"). In this case, you
        don't need the QUERY parameter "external" - use the "externalId" that
        you added to this service. In this case, you need to add the parameter
        "external" ( for ex.: */?external=1*) so the Developer API will search
        by your "externalId" and not by "serviceId" assigned by TIMIFY You can
        add "externalId" to the service with the Developer API endpoints *POST
        /services* and *PATCH /service/:serviceId*
      operationId: deleteV1GroupServicesByGroupserviceid
      responses:
        '200':
          description: >-
            Confirms deletion of the group service and returns the deleted
            service record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: groupServiceId
          in: path
          required: true
          description: Groupserviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Group Services
      summary: Fetch group service
      description: >-
        The URL parameter "groupServiceId" can be used in two ways: - use the
        unique ID of the service assigned by TIMIFY ("groupServiceId"). In this
        case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this service. In this case, you need to
        add the parameter "external" ( for ex.: */?external=1*) so the Developer
        API will search by your "externalId" and not by "serviceId" assigned by
        TIMIFY You can add "externalId" to the service with the Developer API
        endpoints *POST /services* and *PATCH /services/:groupServiceId*
      operationId: getV1GroupServicesByGroupserviceid
      responses:
        '200':
          description: >-
            Returns the specified group service with complete details including
            pricing, capacity, and scheduling information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 75f4c840b6f1a10012ab34cd
                  name: Yoga Fundamentals
                  externalId: EXT-GS-001
                  description: 8-week beginner yoga course for all fitness levels
                  duration: 60
                  durationBefore: 10
                  durationAfter: 5
                  price: 89.99
                  maxParticipants: 15
                  minParticipants: 5
                  currentParticipants: 12
                  isBookable: true
                  isCourse: true
                  color: '#95c5a6'
                  categoryId: 65f4c840b6f1a10012ab34dc
                  categoryName: Wellness
                  resourceIds:
                    - 62ee11a91d66269c365407b1
                  scheduleType: weekly
                  frequency: WEEKS
                  maxCourseRuns: 4
                  upcomingSessions: 8
                  totalCompletedParticipants: 45
                  rating: 4.8
                  reviewCount: 23
                  createdAt: '2025-11-01T10:00:00Z'
                  updatedAt: '2026-03-01T14:30:00Z'
                  ts: 1709305800
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: groupServiceId
          in: path
          required: true
          description: Groupserviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - name: with_full_attributes
          in: query
          required: false
          description: Include full service attributes in the response (true or false).
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Group Services
      summary: Update group service
      description: >-
        The URL parameter "groupServiceId" can be used in two ways: - use the
        unique ID of the group service assigned by TIMIFY ("groupServiceId"). In
        this case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this service. In this case, you need to
        add the parameter "external" ( for ex.: */?external=1*) so the Developer
        API will search by your "externalId" and not by "groupServiceId"
        assigned by TIMIFY You can add "externalId" to the group service with
        the Developer API
      operationId: patchV1GroupServicesByGroupserviceid
      responses:
        '200':
          description: Updates the group service and returns the updated service record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: groupServiceId
          in: path
          required: true
          description: Groupserviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1GroupServicesByGroupserviceidRequest'
      security:
        - BearerAuth: []
  /v1/enterprise-group-services:
    post:
      tags:
        - Enterprise Group Services
      summary: Create enterprise group service
      description: Create a new enterprise-level group service.
      operationId: postV1EnterpriseGroupServices
      responses:
        '201':
          description: >-
            Creates new enterprise-level group service and returns created
            record with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Enterprise group service created
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      externalId: ext-course-001
                      name: Advanced Yoga Workshop
                      description: >-
                        8-week intensive yoga program for intermediate
                        practitioners
                      duration: 60
                      durationBefore: 10
                      durationAfter: 5
                      price: 299.99
                      currency: USD
                      maxParticipants: 20
                      minParticipants: 5
                      isBookable: true
                      isCourse: true
                      categoryId: 65f5d950c7g2b20123bc45de
                      categoryName: Wellness & Fitness
                      resourceIds:
                        - 65f6e061d8h3c31234cd56ef
                      scheduleType: RECURRING
                      frequency: WEEKLY
                      color: '#00AA00'
                      orderIndex: 1
                      createdAt: '2024-03-07T10:30:00Z'
                      updatedAt: '2024-03-07T10:30:00Z'
                      ts: 1709823000
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1EnterpriseGroupServicesRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
    get:
      tags:
        - Enterprise Group Services
      summary: List enterprise group services
      description: >-
        These are services like courses, workshops or events that are offered
        for more than 1 attendee.
      operationId: getV1EnterpriseGroupServices
      responses:
        '200':
          description: >-
            Returns list of enterprise-level group services (courses, workshops,
            events) with their details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              examples:
                success:
                  summary: Enterprise group services list
                  value:
                    data:
                      - id: 65f4c840b6f1a10012ab34cd
                        externalId: ext-course-001
                        name: Advanced Yoga Workshop
                        description: 8-week intensive yoga program
                        duration: 60
                        durationBefore: 10
                        durationAfter: 5
                        price: 299.99
                        maxParticipants: 20
                        minParticipants: 5
                        isBookable: true
                        isCourse: true
                        categoryId: 65f5d950c7g2b20123bc45de
                        resourceIds:
                          - 65f6e061d8h3c31234cd56ef
                        scheduleType: RECURRING
                        frequency: WEEKLY
                      - id: 65f5d951c7g2b20123bc45df
                        externalId: ext-event-001
                        name: Business Conference 2024
                        description: Annual business development conference
                        duration: 480
                        price: 499.99
                        maxParticipants: 500
                        minParticipants: 50
                        isBookable: true
                        isCourse: false
                        categoryId: 65f6e062d8h3c31234cd56eg
                        resourceIds:
                          - 65f7f173e9i4d42345de67fh
                        scheduleType: ONCE
                    status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: with_full_attributes
          in: query
          required: false
          description: Include full service attributes in the response (true or false).
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/enterprise-group-services/categories:
    get:
      tags:
        - Enterprise Group Services
      summary: List enterprise group service categories
      description: List enterprise group service categories.
      operationId: getV1EnterpriseGroupServicesCategories
      responses:
        '200':
          description: >-
            Returns list of enterprise-level group service categories with their
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              examples:
                success:
                  summary: Enterprise group service categories
                  value:
                    data:
                      - id: 65f4c840b6f1a10012ab34cd
                        externalId: ext-cat-wellness
                        name: Wellness & Fitness
                        description: All wellness and fitness courses
                        orderIndex: 1
                        color: '#00AA00'
                        createdAt: '2024-01-15T10:30:00Z'
                        updatedAt: '2024-03-07T14:22:15Z'
                        ts: 1709823735
                      - id: 65f5d950c7g2b20123bc45de
                        externalId: ext-cat-business
                        name: Business Development
                        description: Professional development and business skills
                        orderIndex: 2
                        color: '#0000FF'
                        createdAt: '2024-01-20T09:15:00Z'
                        updatedAt: '2024-03-05T11:45:30Z'
                        ts: 1709741130
                    total: 2
                    meta:
                      page: 1
                      limit: 10
                      totalItems: 2
                      totalPages: 1
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: Filter categories by IDs. Comma-separated list of valid MongoDB IDs.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: resource_id
          in: query
          required: false
          description: Filter categories by resource ID. Must be a valid MongoDB ID.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Enterprise Group Services
      summary: Create enterprise group service category
      description: Create a new enterprise group service category.
      operationId: postV1EnterpriseGroupServicesCategories
      responses:
        '201':
          description: >-
            Creates new enterprise-level group service category and returns
            created record with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Enterprise group service category created
                  value:
                    data:
                      id: 65f6e062d8h3c31234cd56eg
                      externalId: ext-cat-tech
                      name: Technology & IT
                      description: Technology training and IT professional development
                      orderIndex: 3
                      color: '#FF6600'
                      createdAt: '2024-03-07T10:30:00Z'
                      updatedAt: '2024-03-07T10:30:00Z'
                      ts: 1709823000
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PostV1EnterpriseGroupServicesCategoriesRequest
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprise-group-services/categories/{categoryId}:
    delete:
      tags:
        - Enterprise Group Services
      summary: Delete enterprise group service category
      description: >-
        The URL parameter "categoryId" can be used in two ways: - use the unique
        ID of the group service category assigned by TIMIFY ("categoryId"). In
        this case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this group service category. In this
        case, you need to add the parameter "external" ( for ex.:
        */?external=1*) so the Developer API will search by your "externalId"
        and not by "categoryId" assigned by TIMIFY You can add "externalId" to
        the group service with the Developer API endpoints *POST
        /group-services/caetgories* and *PATCH
        /group-service/categories/:categoryId*
      operationId: deleteV1EnterpriseGroupServicesCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Confirms deletion of the enterprise group service category and
            returns the deleted category record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Category deleted
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      externalId: ext-cat-wellness
                      name: Wellness & Fitness
                      description: All wellness and fitness courses
                      orderIndex: 1
                      color: '#00AA00'
                      deletedAt: '2024-03-07T14:22:15Z'
                      ts: 1709823735
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Enterprise Group Services
      summary: Fetch enterprise service group category
      description: >-
        The URL parameter "categoryId" can be used in two ways: - use the unique
        ID of the group service category assigned by TIMIFY ("categoryId"). In
        this case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this group service category. In this
        case, you need to add the parameter "external" ( for ex.:
        */?external=1*) so the Developer API will search by your "externalId"
        and not by "categoryId" assigned by TIMIFY You can add "externalId" to
        the service category with the Developer API endpoints *POST
        /services/categories* and *PATCH /services/categories/:categoryId*
      operationId: getV1EnterpriseGroupServicesCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Returns the specified enterprise group service category with its
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Category details
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      externalId: ext-cat-wellness
                      name: Wellness & Fitness
                      description: All wellness and fitness courses
                      orderIndex: 1
                      color: '#00AA00'
                      servicesCount: 5
                      createdAt: '2024-01-15T10:30:00Z'
                      updatedAt: '2024-03-07T14:22:15Z'
                      ts: 1709823735
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Enterprise Group Services
      summary: Update enterprise group service category
      description: Update an enterprise group service category.
      operationId: patchV1EnterpriseGroupServicesCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Updates the enterprise group service category and returns the
            updated category record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Category updated
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      externalId: ext-cat-wellness
                      name: Wellness & Fitness Programs
                      description: >-
                        Comprehensive wellness and fitness courses for all
                        levels
                      orderIndex: 2
                      color: '#00BB00'
                      servicesCount: 5
                      updatedAt: '2024-03-07T14:22:15Z'
                      ts: 1709823735
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PatchV1EnterpriseGroupServicesCategoriesByCategoryidRequest
      security:
        - BearerAuth: []
  /v1/enterprise-group-services/{groupServiceId}:
    delete:
      tags:
        - Enterprise Group Services
      summary: Delete enterprise group service
      description: >-
        The URL parameter "serviceId" can be used in two ways: - use the unique
        ID of the service assigned by TIMIFY ("serviceId"). In this case, you
        don't need the QUERY parameter "external" - use the "externalId" that
        you added to this service. In this case, you need to add the parameter
        "external" ( for ex.: */?external=1*) so the Developer API will search
        by your "externalId" and not by "serviceId" assigned by TIMIFY You can
        add "externalId" to the service with the Developer API endpoints *POST
        /services* and *PATCH /service/:serviceId*
      operationId: deleteV1EnterpriseGroupServicesByGroupserviceid
      responses:
        '200':
          description: >-
            Confirms deletion of the enterprise group service and returns the
            deleted service record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Enterprise group service deleted
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      externalId: ext-course-001
                      name: Advanced Yoga Workshop
                      price: 299.99
                      maxParticipants: 20
                      deletedAt: '2024-03-07T14:22:15Z'
                      ts: 1709823735
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: groupServiceId
          in: path
          required: true
          description: Groupserviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Enterprise Group Services
      summary: Fetch enterprise group service
      description: >-
        The URL parameter "groupServiceId" can be used in two ways: - use the
        unique ID of the service assigned by TIMIFY ("groupServiceId"). In this
        case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this service. In this case, you need to
        add the parameter "external" ( for ex.: */?external=1*) so the Developer
        API will search by your "externalId" and not by "serviceId" assigned by
        TIMIFY You can add "externalId" to the service with the Developer API
        endpoints *POST /services* and *PATCH /services/:groupServiceId*
      operationId: getV1EnterpriseGroupServicesByGroupserviceid
      responses:
        '200':
          description: >-
            Returns the specified enterprise group service with complete details
            including pricing, capacity, and scheduling information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Enterprise group service details
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      externalId: ext-course-001
                      name: Advanced Yoga Workshop
                      description: >-
                        8-week intensive yoga program for intermediate
                        practitioners
                      duration: 60
                      durationBefore: 10
                      durationAfter: 5
                      price: 299.99
                      currency: USD
                      maxParticipants: 20
                      minParticipants: 5
                      currentParticipants: 12
                      isBookable: true
                      isCourse: true
                      categoryId: 65f5d950c7g2b20123bc45de
                      categoryName: Wellness & Fitness
                      resourceIds:
                        - 65f6e061d8h3c31234cd56ef
                      scheduleType: RECURRING
                      frequency: WEEKLY
                      upcomingSessions: 8
                      totalCompletedParticipants: 45
                      color: '#00AA00'
                      orderIndex: 1
                      createdAt: '2024-03-01T10:30:00Z'
                      updatedAt: '2024-03-07T14:22:15Z'
                      ts: 1709823735
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: groupServiceId
          in: path
          required: true
          description: Groupserviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - name: with_full_attributes
          in: query
          required: false
          description: Include full service attributes in the response (true or false).
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Enterprise Group Services
      summary: Update enterprise group service
      description: >-
        The URL parameter "groupServiceId" can be used in two ways: - use the
        unique ID of the group service assigned by TIMIFY ("groupServiceId"). In
        this case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this service. In this case, you need to
        add the parameter "external" ( for ex.: */?external=1*) so the Developer
        API will search by your "externalId" and not by "groupServiceId"
        assigned by TIMIFY You can add "externalId" to the group service with
        the Developer API
      operationId: patchV1EnterpriseGroupServicesByGroupserviceid
      responses:
        '200':
          description: >-
            Updates the enterprise group service and returns the updated service
            record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Enterprise group service updated
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      externalId: ext-course-001
                      name: Advanced Yoga Workshop - Spring 2024
                      description: >-
                        10-week intensive yoga program for intermediate
                        practitioners
                      duration: 75
                      durationBefore: 10
                      durationAfter: 5
                      price: 349.99
                      currency: USD
                      maxParticipants: 25
                      minParticipants: 5
                      isBookable: true
                      isCourse: true
                      categoryId: 65f5d950c7g2b20123bc45de
                      resourceIds:
                        - 65f6e061d8h3c31234cd56ef
                      scheduleType: RECURRING
                      frequency: WEEKLY
                      color: '#00AA00'
                      updatedAt: '2024-03-07T14:22:15Z'
                      ts: 1709823735
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: groupServiceId
          in: path
          required: true
          description: Groupserviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PatchV1EnterpriseGroupServicesByGroupserviceidRequest
      security:
        - BearerAuth: []
  /v1/ics/companies:
    get:
      tags:
        - ICS
      summary: Get companies
      description: List ICS calendar subscription configurations for the company.
      operationId: getV1IcsCompanies
      responses:
        '200':
          description: >-
            Returns paginated list of ICS calendar subscription configurations
            for the company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              examples:
                success:
                  summary: ICS subscriptions list
                  value:
                    data:
                      - id: 65f4c840b6f1a10012ab34cd
                        companyId: 65f5d950c7g2b20123bc45de
                        icsUrl: >-
                          https://api.timify.io/ics/companies/65f5d950c7g2b20123bc45de/calendar.ics
                        enabled: true
                        createdAt: '2024-02-15T08:30:00Z'
                        updatedAt: '2024-03-07T10:15:00Z'
                        ts: 1709798100
                      - id: 65f5d951c7g2b20123bc45df
                        companyId: 65f5d950c7g2b20123bc45de
                        icsUrl: >-
                          https://api.timify.io/ics/companies/65f5d950c7g2b20123bc45de/calendar-backup.ics
                        enabled: false
                        createdAt: '2024-03-01T14:20:00Z'
                        updatedAt: '2024-03-05T09:45:00Z'
                        ts: 1709629500
                    total: 2
                    meta:
                      page: 1
                      limit: 10
                      totalItems: 2
                      totalPages: 1
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/ics/companies/subscription:
    post:
      tags:
        - ICS
      summary: Post subscription
      description: Enable or disable an ICS calendar subscription for the company.
      operationId: postV1IcsCompaniesSubscription
      responses:
        '201':
          description: >-
            Enables or disables ICS calendar subscription and returns
            configuration confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Company ICS subscription enabled
                  value:
                    data:
                      id: 65f6e062d8h3c31234cd56eg
                      companyId: 65f5d950c7g2b20123bc45de
                      icsUrl: >-
                        https://api.timify.io/ics/companies/65f5d950c7g2b20123bc45de/calendar.ics
                      enabled: true
                      createdAt: '2024-03-07T15:30:00Z'
                      updatedAt: '2024-03-07T15:30:00Z'
                      ts: 1709831400
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1IcsCompaniesSubscriptionRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/ics/resources:
    get:
      tags:
        - ICS
      summary: Get resources
      description: List ICS calendar subscription configurations for resources.
      operationId: getV1IcsResources
      responses:
        '200':
          description: >-
            Returns paginated list of ICS calendar subscription configurations
            for resources.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              examples:
                success:
                  summary: Resource ICS subscriptions list
                  value:
                    data:
                      - id: 65f4c840b6f1a10012ab34cd
                        resourceId: 62ee11a91d66269c365407b1
                        resourceName: John Smith
                        icsUrl: >-
                          https://api.timify.io/ics/resources/62ee11a91d66269c365407b1/calendar.ics
                        enabled: true
                        createdAt: '2024-02-10T09:00:00Z'
                        updatedAt: '2024-03-07T11:20:00Z'
                        ts: 1709801400
                      - id: 65f5d951c7g2b20123bc45df
                        resourceId: 62ee11a91d66269c365407b2
                        resourceName: Jane Doe
                        icsUrl: >-
                          https://api.timify.io/ics/resources/62ee11a91d66269c365407b2/calendar.ics
                        enabled: true
                        createdAt: '2024-02-20T10:30:00Z'
                        updatedAt: '2024-03-06T14:45:00Z'
                        ts: 1709731500
                    total: 2
                    meta:
                      page: 1
                      limit: 10
                      totalItems: 2
                      totalPages: 1
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/ics/resources/subscription:
    post:
      tags:
        - ICS
      summary: Post subscription
      description: Enable or disable an ICS calendar subscription for a resource.
      operationId: postV1IcsResourcesSubscription
      responses:
        '201':
          description: >-
            Enables or disables ICS calendar subscription for resources and
            returns configuration confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Resource ICS subscription enabled
                  value:
                    data:
                      id: 65f6e062d8h3c31234cd56eg
                      resourceId: 62ee11a91d66269c365407b3
                      resourceName: Mark Johnson
                      icsUrl: >-
                        https://api.timify.io/ics/resources/62ee11a91d66269c365407b3/calendar.ics
                      enabled: true
                      createdAt: '2024-03-07T16:00:00Z'
                      updatedAt: '2024-03-07T16:00:00Z'
                      ts: 1709832000
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1IcsResourcesSubscriptionRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/notifications:
    delete:
      tags:
        - Notifications
      summary: Cancel scheduled email
      description: Cancel a scheduled email notification before it is sent.
      operationId: deleteV1Notifications
      responses:
        '200':
          description: >-
            Cancels scheduled email notifications and returns cancellation
            confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Email notification cancelled
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      reference: appt_65f5d950c7g2b20123bc45de
                      recipientEmail: john.doe@example.com
                      subject: Your appointment reminder
                      notificationType: appointment_reminder
                      status: cancelled
                      scheduledAt: '2024-03-08T09:00:00Z'
                      cancelledAt: '2024-03-07T15:45:00Z'
                      ts: 1709833500
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: refs
          in: query
          required: false
          description: Filter notifications to cancel by reference IDs (comma-separated).
          schema:
            type: string
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Notifications
      summary: Send email notification
      description: Send or queue a notification for an appointment or customer event.
      operationId: postV1Notifications
      responses:
        '201':
          description: >-
            Sends or queues notification for appointment or customer event and
            returns created record with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Email notification sent
                  value:
                    data:
                      id: 65f6e062d8h3c31234cd56eg
                      reference: appt_65f7f173e9i4d42345de67fh
                      recipientEmail: jane.smith@example.com
                      recipientName: Jane Smith
                      subject: Appointment confirmation - Hair Cut
                      notificationType: appointment_confirmation
                      status: sent
                      appointmentId: 65f7f173e9i4d42345de67fh
                      appointmentTime: '2024-03-10T14:00:00Z'
                      serviceName: Hair Cut
                      resourceName: Station 2
                      sentAt: '2024-03-07T15:50:00Z'
                      createdAt: '2024-03-07T15:50:00Z'
                      ts: 1709833800
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1NotificationsRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprise-permissions/groups:
    get:
      tags:
        - Permissions
      summary: List enterprise permission groups
      description: List permission groups for the enterprise.
      operationId: getV1EnterprisePermissionsGroups
      responses:
        '200':
          description: >-
            Returns paginated list of enterprise permission groups with their
            details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              examples:
                success:
                  summary: Permission groups list
                  value:
                    data:
                      - id: 65f4c840b6f1a10012ab34cd
                        name: Admin Group
                        description: Full administrative access
                        permissions:
                          - manage_companies
                          - manage_users
                          - view_analytics
                          - manage_settings
                          - manage_billing
                        membersCount: 2
                        isGloballyDeleted: false
                        isUpdatedLocally: false
                        createdAt: '2024-01-15T10:30:00Z'
                        updatedAt: '2024-03-07T14:22:15Z'
                        ts: 1709823735
                      - id: 65f5d950c7g2b20123bc45de
                        name: Manager Group
                        description: Managers can view analytics and manage users
                        permissions:
                          - manage_users
                          - view_analytics
                        membersCount: 5
                        isGloballyDeleted: false
                        isUpdatedLocally: false
                        createdAt: '2024-02-01T09:15:00Z'
                        updatedAt: '2024-03-05T11:45:30Z'
                        ts: 1709741130
                    total: 2
                    meta:
                      page: 1
                      limit: 10
                      totalItems: 2
                      totalPages: 1
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: >-
            Filter permission groups by IDs. Comma-separated list of valid
            MongoDB IDs.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: internal_id
          in: query
          required: false
          description: Filter permission groups by internal ID. Must be a valid MongoDB ID.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: is_globally_deleted
          in: query
          required: false
          description: Filter permission groups by global deletion status (true or false).
          schema:
            type: boolean
          example: true
        - name: is_updated_locally
          in: query
          required: false
          description: Filter permission groups by local update status (true or false).
          schema:
            type: boolean
          example: true
        - name: only_locals
          in: query
          required: false
          description: Filter to return only locally modified permission groups.
          schema:
            type: string
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Permissions
      summary: Create enterprise permission groups
      description: Create a new permission group.
      operationId: postV1EnterprisePermissionsGroups
      responses:
        '201':
          description: >-
            Creates new enterprise permission group and returns created record
            with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Permission group created
                  value:
                    data:
                      id: 65f6e062d8h3c31234cd56eg
                      name: Editor Group
                      description: Can edit content and manage appointments
                      permissions:
                        - manage_users
                        - manage_services
                        - view_analytics
                      membersCount: 0
                      isGloballyDeleted: false
                      isUpdatedLocally: false
                      createdAt: '2024-03-07T15:45:00Z'
                      updatedAt: '2024-03-07T15:45:00Z'
                      ts: 1709831100
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1EnterprisePermissionsGroupsRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprise-permissions/groups/{groupId}:
    delete:
      tags:
        - Permissions
      summary: Delete enterprise permission group
      description: Delete an enterprise permission group.
      operationId: deleteV1EnterprisePermissionsGroupsByGroupid
      responses:
        '200':
          description: >-
            Confirms deletion of the permission group and returns the deleted
            group record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Permission group deleted
                  value:
                    data:
                      id: 65f6e062d8h3c31234cd56eg
                      name: Editor Group
                      description: Can edit content and manage appointments
                      permissions:
                        - manage_users
                        - manage_services
                        - view_analytics
                      membersCount: 1
                      isGloballyDeleted: true
                      isUpdatedLocally: false
                      deletedAt: '2024-03-07T16:00:30Z'
                      ts: 1709832030
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: groupId
          in: path
          required: true
          description: Groupid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Permissions
      summary: Fetch enterprise permission group
      description: Fetch a specific enterprise permission group.
      operationId: getV1EnterprisePermissionsGroupsByGroupid
      responses:
        '200':
          description: >-
            Returns the specified permission group with its details and assigned
            permissions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Permission group detail
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      name: Admin Group
                      description: Full administrative access
                      permissions:
                        - manage_companies
                        - manage_users
                        - view_analytics
                        - manage_settings
                        - manage_billing
                      membersCount: 2
                      isGloballyDeleted: false
                      isUpdatedLocally: false
                      createdAt: '2024-01-15T10:30:00Z'
                      updatedAt: '2024-03-07T14:22:15Z'
                      ts: 1709823735
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: groupId
          in: path
          required: true
          description: Groupid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Permissions
      summary: Update enterprise permission group
      description: Update an enterprise permission group.
      operationId: patchV1EnterprisePermissionsGroupsByGroupid
      responses:
        '200':
          description: Updates the permission group and returns the updated group record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Permission group updated
                  value:
                    data:
                      id: 65f5d950c7g2b20123bc45de
                      name: Manager Group
                      description: >-
                        Managers can view analytics and manage users and
                        services
                      permissions:
                        - manage_users
                        - manage_services
                        - view_analytics
                      membersCount: 5
                      isGloballyDeleted: false
                      isUpdatedLocally: false
                      createdAt: '2024-02-01T09:15:00Z'
                      updatedAt: '2024-03-07T16:15:45Z'
                      ts: 1709832945
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: groupId
          in: path
          required: true
          description: Groupid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PatchV1EnterprisePermissionsGroupsByGroupidRequest
      security:
        - BearerAuth: []
  /v1/timezones:
    get:
      tags:
        - Public
      summary: List timezones
      description: Get all available timezones used in the TIMIFY Developer API
      operationId: getV1Timezones
      responses:
        '200':
          description: >-
            Returns paginated list of all available timezones used in the TIMIFY
            Developer API.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              examples:
                success:
                  summary: Timezones list
                  value:
                    data:
                      - id: 1
                        name: UTC
                        region: Etc/UTC
                        abbreviation: UTC
                        offsetHours: 0
                        offsetMinutes: 0
                        isDaylight: false
                      - id: 2
                        name: Europe/Berlin
                        region: Europe/Berlin
                        abbreviation: CET
                        offsetHours: 1
                        offsetMinutes: 0
                        isDaylight: false
                      - id: 3
                        name: America/New_York
                        region: America/New_York
                        abbreviation: EST
                        offsetHours: -5
                        offsetMinutes: 0
                        isDaylight: false
                      - id: 4
                        name: Asia/Tokyo
                        region: Asia/Tokyo
                        abbreviation: JST
                        offsetHours: 9
                        offsetMinutes: 0
                        isDaylight: false
                      - id: 5
                        name: Australia/Sydney
                        region: Australia/Sydney
                        abbreviation: AEDT
                        offsetHours: 11
                        offsetMinutes: 0
                        isDaylight: true
                    total: 5
                    meta:
                      page: 1
                      limit: 10
                      totalItems: 5
                      totalPages: 1
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
      security: []
  /v1/enterprise-resources/categories:
    get:
      tags:
        - Enterprise Resource Categories
      summary: List enterprise resources categories
      description: List resource categories at the enterprise level.
      operationId: getV1EnterpriseResourcesCategories
      responses:
        '200':
          description: >-
            Returns paginated list of resource categories used to organize
            resources at the enterprise level.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34cd
                    externalId: RC-STAFF
                    name: Staff Resources
                    description: Employees and team members
                    orderIndex: 0
                    isDefault: true
                    isDependency: false
                    createdAt: '2024-01-10T09:00:00Z'
                    updatedAt: '2024-02-20T14:45:30Z'
                    ts: 1707998730
                  - id: 65f4c840b6f1a10012ab34ce
                    externalId: RC-EQUIPMENT
                    name: Equipment Resources
                    description: Physical equipment and facilities
                    orderIndex: 1
                    isDefault: false
                    isDependency: false
                    createdAt: '2024-01-12T11:30:00Z'
                    updatedAt: '2024-02-18T09:30:00Z'
                    ts: 1708249800
                  - id: 65f4c840b6f1a10012ab34cf
                    externalId: RC-ROOMS
                    name: Meeting Rooms
                    description: Conference and meeting spaces
                    orderIndex: 2
                    isDefault: false
                    isDependency: true
                    createdAt: '2024-01-15T14:20:00Z'
                    updatedAt: '2024-02-25T10:15:00Z'
                    ts: 1708774500
                total: 8
                meta:
                  page: 1
                  limit: 20
                  totalItems: 8
                  totalPages: 1
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: >-
            Filter results by resource category IDs. Accepts array of valid
            MongoDB ObjectIds.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Enterprise Resource Categories
      summary: Create enterprise resource category.
      description: Create an enterprise resource category.
      operationId: postV1EnterpriseResourcesCategories
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: RC-STAFF
                  name: Staff Resources
                  description: Employees and team members
                  orderIndex: 0
                  isDefault: true
                  isDependency: false
                  createdAt: '2024-03-01T10:30:00Z'
                  updatedAt: '2024-03-01T10:30:00Z'
                  ts: 1709283000
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1EnterpriseResourcesCategoriesRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprise-resources/categories/{categoryId}:
    delete:
      tags:
        - Enterprise Resource Categories
      summary: Delete enterprise resource category
      description: Delete an enterprise resource category.
      operationId: deleteV1EnterpriseResourcesCategoriesByCategoryid
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Enterprise Resource Categories
      summary: Fetch enterprise category resource
      description: >-
        The URL parameter "categoryId" can be used in two ways: - use the unique
        ID of the resource category assigned by TIMIFY ("categoryId"). In this
        case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this resource category. In this case, you
        need to add the parameter "external" ( for ex.:*/?external=1*) so the
        Developer API will search by your "externalId" and not by "categoryId"
        assigned by TIMIFY You can add "externalId" to the resource category
        with the Developer API endpoints *POST /resources/categories* and *PATCH
        resources/cartegories/:categoryId*
      operationId: getV1EnterpriseResourcesCategoriesByCategoryid
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: RC-STAFF
                  name: Staff Resources
                  description: Employees and team members
                  orderIndex: 0
                  isDefault: true
                  isDependency: false
                  createdAt: '2024-01-10T09:00:00Z'
                  updatedAt: '2024-02-20T14:45:30Z'
                  ts: 1707998730
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Enterprise Resource Categories
      summary: Update enterprise resource category
      description: Update an enterprise resource category.
      operationId: patchV1EnterpriseResourcesCategoriesByCategoryid
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: RC-STAFF
                  name: Staff Resources
                  description: Employees and team members (Updated)
                  orderIndex: 0
                  isDefault: true
                  isDependency: false
                  createdAt: '2024-01-10T09:00:00Z'
                  updatedAt: '2024-03-01T16:00:00Z'
                  ts: 1709307600
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PatchV1EnterpriseResourcesCategoriesByCategoryidRequest
      security:
        - BearerAuth: []
  /v1/resources:
    get:
      tags:
        - Resources
      summary: Lists resources
      description: List resources (staff members, rooms, or equipment) for the company.
      operationId: getV1Resources
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34cd
                    externalId: RES-STAFF-001
                    globalId: internal-id
                    name: John Smith
                    email: john.smith@example.com
                    categoryId: 65f4c840b6f1a10012ab34ce
                    categoryName: Staff
                    isBookable: true
                    isAdmin: false
                    color: '#0066CC'
                    avatarUrl: https://api.timify.com/avatars/res-123.jpg
                    orderIndex: 1
                    createdAt: '2024-01-15T10:30:00Z'
                    updatedAt: '2024-02-20T14:45:30Z'
                    ts: 1708430730
                  - id: 65f4c840b6f1a10012ab34ce
                    externalId: RES-EQUIPMENT-001
                    globalId: internal-id-2
                    name: Conference Room A
                    email: null
                    categoryId: 65f4c840b6f1a10012ab34cf
                    categoryName: Equipment
                    isBookable: true
                    isAdmin: false
                    color: '#FF9900'
                    avatarUrl: null
                    orderIndex: 2
                    createdAt: '2024-01-20T08:15:00Z'
                    updatedAt: '2024-02-15T16:30:00Z'
                    ts: 1708067400
                total: 12
                meta:
                  page: 1
                  limit: 20
                  totalItems: 12
                  totalPages: 1
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: >-
            Filter results by resource IDs. Accepts array of valid MongoDB
            ObjectIds.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: external_ids
          in: query
          required: false
          description: >-
            Filter resources by external IDs. Accepts array of external ID
            strings.
          schema:
            type: array
            items:
              type: string
              example: EXT-RESOURCE-001
            minItems: 1
          example:
            - EXT-RESOURCE-001
        - name: category_id
          in: query
          required: false
          description: >-
            Filter resources by category. Accepts valid MongoDB ObjectId of a
            resource category.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: email
          in: query
          required: false
          description: Filter resources by email address. Exact match on resource email.
          schema:
            type: string
            format: email
          example: alex@example.com
        - name: name
          in: query
          required: false
          description: >-
            Search resources by name. Performs text search on resource name
            field.
          schema:
            type: string
        - name: bookable
          in: query
          required: false
          description: >-
            Filter bookable resources. Set to true to show only bookable
            resources.
          schema:
            type: boolean
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: sort_type
          in: query
          required: false
          description: >-
            Sort direction. Accepts "asc" (ascending) or "desc" (descending).
            Default: asc.
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: sort
          in: query
          required: false
          description: Sort results by field. Typically "name" or "createdAt".
          schema:
            type: string
        - name: with_full_attributes
          in: query
          required: false
          description: >-
            Include complete resource attributes in response. Set to true for
            detailed resource information.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Resources
      summary: Create new resource
      description: Create a new resource.
      operationId: postV1Resources
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: RES-STAFF-001
                  globalId: internal-id
                  name: John Smith
                  email: john.smith@example.com
                  categoryId: 65f4c840b6f1a10012ab34ce
                  categoryName: Staff
                  isBookable: true
                  isAdmin: false
                  color: '#0066CC'
                  avatarUrl: https://api.timify.com/avatars/res-123.jpg
                  orderIndex: 1
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: '2024-01-15T10:30:00Z'
                  ts: 1705324200
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ResourcesRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/resources/categories:
    get:
      tags:
        - Resources
      summary: List resources categories
      description: List resource categories.
      operationId: getV1ResourcesCategories
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34ce
                    externalId: CAT-STAFF
                    name: Staff
                    description: Employee resources
                    orderIndex: 0
                    isDefault: true
                    isDependency: false
                    createdAt: '2024-01-10T09:00:00Z'
                    updatedAt: '2024-02-20T14:45:30Z'
                    ts: 1707998730
                  - id: 65f4c840b6f1a10012ab34cf
                    externalId: CAT-EQUIPMENT
                    name: Equipment
                    description: Physical equipment and facilities
                    orderIndex: 1
                    isDefault: false
                    isDependency: false
                    createdAt: '2024-01-12T11:30:00Z'
                    updatedAt: '2024-02-15T10:00:00Z'
                    ts: 1707988200
                  - id: 65f4c840b6f1a10012ab34d0
                    externalId: CAT-ROOMS
                    name: Meeting Rooms
                    description: Conference and meeting spaces
                    orderIndex: 2
                    isDefault: false
                    isDependency: true
                    createdAt: '2024-01-15T14:20:00Z'
                    updatedAt: '2024-02-18T09:30:00Z'
                    ts: 1708249800
                total: 3
                meta:
                  page: 1
                  limit: 20
                  totalItems: 3
                  totalPages: 1
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: >-
            Filter results by resource category IDs. Accepts array of valid
            MongoDB ObjectIds.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Resources
      summary: Create resource category
      description: Create a new resource category.
      operationId: postV1ResourcesCategories
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34ce
                  externalId: CAT-STAFF
                  name: Staff
                  description: Employee resources
                  orderIndex: 0
                  isDefault: true
                  isDependency: false
                  createdAt: '2024-03-01T10:30:00Z'
                  updatedAt: '2024-03-01T10:30:00Z'
                  ts: 1709283000
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ResourcesCategoriesRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/resources/categories/{categoryId}:
    delete:
      tags:
        - Resources
      summary: Delete resource category
      description: Delete a resource category.
      operationId: deleteV1ResourcesCategoriesByCategoryid
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Resources
      summary: Fetch category resource
      description: >-
        The URL parameter "categoryId" can be used in two ways: - use the unique
        ID of the resource category assigned by TIMIFY ("categoryId"). In this
        case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this resource category. In this case, you
        need to add the parameter "external" ( for ex.:*/?external=1*) so the
        Developer API will search by your "externalId" and not by "categoryId"
        assigned by TIMIFY You can add "externalId" to the resource category
        with the Developer API endpoints *POST /resources/categories* and *PATCH
        resources/cartegories/:categoryId*
      operationId: getV1ResourcesCategoriesByCategoryid
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34ce
                  externalId: CAT-STAFF
                  name: Staff
                  description: Employee resources
                  orderIndex: 0
                  isDefault: true
                  isDependency: false
                  createdAt: '2024-01-10T09:00:00Z'
                  updatedAt: '2024-02-20T14:45:30Z'
                  ts: 1707998730
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Resources
      summary: Update resource category
      description: Update a resource category.
      operationId: patchV1ResourcesCategoriesByCategoryid
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34ce
                  externalId: CAT-STAFF
                  name: Staff Members
                  description: Employee resources and staff
                  orderIndex: 0
                  isDefault: true
                  isDependency: false
                  createdAt: '2024-01-10T09:00:00Z'
                  updatedAt: '2024-03-01T16:00:00Z'
                  ts: 1709307600
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PatchV1ResourcesCategoriesByCategoryidRequest
      security:
        - BearerAuth: []
  /v1/resources/{resourceId}:
    delete:
      tags:
        - Resources
      summary: Delete resource by ID
      description: Delete a resource.
      operationId: deleteV1ResourcesByResourceid
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: resourceId
          in: path
          required: true
          description: Resourceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Resources
      summary: Fetch resource
      description: >-
        The URL parameter "resourceId" can be used in two ways: - use the unique
        ID of the resource assigned by TIMIFY ("resourceId"). In this case, you
        don't need the QUERY parameter "external" - use the "externalId" that
        you added to this resource. In this case, you need to add the parameter
        "external" ( for ex.: */?external=1*) so the Developer API will search
        by your "externalId" and not by "resourceId" assigned by TIMIFY You can
        add "externalId" to the resource with the Developer API endpoints *POST
        /resources* and *PATCH resources/:resourceId*
      operationId: getV1ResourcesByResourceid
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: RES-STAFF-001
                  globalId: internal-id
                  name: John Smith
                  email: john.smith@example.com
                  categoryId: 65f4c840b6f1a10012ab34ce
                  categoryName: Staff
                  isBookable: true
                  isAdmin: false
                  color: '#0066CC'
                  avatarUrl: https://api.timify.com/avatars/res-123.jpg
                  orderIndex: 1
                  timezone: Europe/Berlin
                  permissions: read,write
                  bookingTimes:
                    - start: '09:00'
                      end: '17:00'
                      day: 1
                  workingTimes:
                    - start: '08:30'
                      end: '17:30'
                      day: 1
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: '2024-02-20T14:45:30Z'
                  ts: 1708430730
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: resourceId
          in: path
          required: true
          description: Resourceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - name: with_full_attributes
          in: query
          required: false
          description: >-
            Include complete resource attributes in response. Set to true for
            detailed resource information.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Resources
      summary: Update resource
      description: Update a resource.
      operationId: patchV1ResourcesByResourceid
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: RES-STAFF-001
                  globalId: internal-id
                  name: John Smith
                  email: john.smith@example.com
                  categoryId: 65f4c840b6f1a10012ab34ce
                  categoryName: Staff
                  isBookable: true
                  isAdmin: false
                  color: '#0066CC'
                  avatarUrl: https://api.timify.com/avatars/res-123.jpg
                  orderIndex: 1
                  timezone: Europe/Berlin
                  permissions: read,write,delete
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: '2024-03-01T15:20:00Z'
                  ts: 1709297400
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: resourceId
          in: path
          required: true
          description: Resourceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1ResourcesByResourceidRequest'
      security:
        - BearerAuth: []
  /v1/resources/{resourceId}/settings:
    patch:
      tags:
        - Resources
      summary: Update resource settings
      description: >-
        Update the settings (e.g. booking preferences, visibility) for a
        specific resource.
      operationId: patchV1ResourcesByResourceidSettings
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: resourceId
          in: path
          required: true
          description: Resourceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1ResourcesByResourceidSettingsRequest'
      security:
        - BearerAuth: []
  /v1/resources/{resourceId}/unlink:
    get:
      tags:
        - Resources
      summary: Unlink resource
      description: Remove a resource from a company or a branch
      operationId: getV1ResourcesByResourceidUnlink
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: resourceId
          in: path
          required: true
          description: Resourceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/enterprise-services:
    get:
      tags:
        - Enterprise Services
      summary: List enterprise services
      description: >-
        This endpoint retrieves all the enterprise services. When the developer
        wants to include booking limit suggestions in the response, the booking
        limitation params needs to be be included in the query, only the
        `start_date` is mandatory ``` ?start_date=2019-02-23
        11:30&event_id=645515845089ba22acfa569e&durations_pattern=5&duration_before=30&duration_after=30
        ```
      operationId: getV1EnterpriseServices
      responses:
        '200':
          description: >-
            Returns paginated list of enterprise services with optional booking
            limit suggestions based on provided date/time parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34cd
                    externalId: SVC-CONSULTATION-001
                    name: Consultation
                    description: 30-minute one-on-one consultation session
                    duration: 30
                    durationBefore: 10
                    durationAfter: 5
                    price: 99.99
                    isBookable: true
                    isCourse: false
                    color: '#1976d2'
                    categoryId: 646377d319354093d997f819
                    categoryName: Services
                    resourceIds:
                      - 62ee11a91d66269c365407b1
                      - 62ee11a91d66269c365407b2
                    maxParticipants: 1
                    maxWaitlistParticipants: 5
                    bookingLimitSuggestions:
                      - resourceId: 62ee11a91d66269c365407b1
                        availableSlots: 5
                    createdAt: '2024-01-15T10:30:00Z'
                    updatedAt: '2024-02-20T14:45:30Z'
                    ts: 1708430730
                  - id: 65f4c840b6f1a10012ab34ce
                    externalId: SVC-MASSAGE-001
                    name: Swedish Massage
                    description: Full body Swedish massage (60 minutes)
                    duration: 60
                    durationBefore: 15
                    durationAfter: 10
                    price: 149.99
                    isBookable: true
                    isCourse: false
                    color: '#ff9800'
                    categoryId: 646377d319354093d997f81a
                    categoryName: Wellness
                    resourceIds:
                      - 62ee11a91d66269c365407b3
                    maxParticipants: 1
                    maxWaitlistParticipants: 3
                    bookingLimitSuggestions:
                      - resourceId: 62ee11a91d66269c365407b3
                        availableSlots: 3
                    createdAt: '2024-01-20T14:30:00Z'
                    updatedAt: '2024-02-15T11:00:00Z'
                    ts: 1708058400
                total: 42
                meta:
                  page: 1
                  limit: 20
                  totalItems: 42
                  totalPages: 3
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: is_bookable
          in: query
          required: false
          description: >-
            Filter results to only bookable services. Set to true to exclude
            non-bookable services.
          schema:
            type: boolean
          example: true
        - name: category_id
          in: query
          required: false
          description: >-
            Filter services by category. Accepts valid MongoDB ObjectId of a
            service category.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: resource_id
          in: query
          required: false
          description: >-
            Filter services assigned to a specific resource. Accepts valid
            MongoDB ObjectId.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: resource_category_id
          in: query
          required: false
          description: >-
            Filter services by resource category. Accepts valid MongoDB ObjectId
            of a resource category.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: ids
          in: query
          required: false
          description: >-
            Filter results by service IDs. Accepts array of valid MongoDB
            ObjectIds.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: external_ids
          in: query
          required: false
          description: >-
            Filter services by external IDs. Accepts array of external ID
            strings.
          schema:
            type: array
            items:
              type: string
              example: EXT-SERVICE-001
            minItems: 1
          example:
            - EXT-SERVICE-001
        - name: is_stalled
          in: query
          required: false
          description: >-
            Filter stalled services. Set to true to show only temporarily paused
            services.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: sort_type
          in: query
          required: false
          description: >-
            Sort direction. Accepts "asc" (ascending) or "desc" (descending).
            Default: asc.
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: sort
          in: query
          required: false
          description: Sort results by field. Typically "name" or "createdAt".
          schema:
            type: string
        - name: start_date
          in: query
          required: false
          description: >-
            Start date for availability checks in booking limit suggestions.
            Format: YYYY-MM-DD HH:mm.
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2026-03-02 09:00
        - name: event_id
          in: query
          required: false
          description: Filter services by event. Accepts valid MongoDB ObjectId.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: durations_pattern[]
          in: query
          required: false
          description: >-
            Duration availability pattern. Must be divisible by 5 (minutes).
            Include multiple times for varied availability.
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 20
        - name: duration_before
          in: query
          required: false
          description: Buffer time before service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - name: duration_after
          in: query
          required: false
          description: Buffer time after service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Enterprise Services
      summary: Create enterprise service
      description: Create a new enterprise-level service.
      operationId: postV1EnterpriseServices
      responses:
        '201':
          description: >-
            Creates new enterprise service and returns created service record
            with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: start_date
          in: query
          required: false
          description: 'Start date for service availability. Format: YYYY-MM-DD HH:mm.'
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2026-03-02 09:00
        - name: event_id
          in: query
          required: false
          description: Associate service with event. Accepts valid MongoDB ObjectId.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: durations_pattern[]
          in: query
          required: false
          description: >-
            Duration availability pattern. Must be divisible by 5 (minutes).
            Include multiple times for varied availability.
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 20
        - name: duration_before
          in: query
          required: false
          description: Buffer time before service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - name: duration_after
          in: query
          required: false
          description: Buffer time after service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1EnterpriseServicesRequest'
      security:
        - BearerAuth: []
  /v1/enterprise-services/categories:
    get:
      tags:
        - Enterprise Services
      summary: List enterprise service categories
      description: List enterprise service categories.
      operationId: getV1EnterpriseServicesCategories
      responses:
        '200':
          description: >-
            Returns paginated list of enterprise service categories that
            organize services.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: >-
            Filter results by category IDs. Accepts array of valid MongoDB
            ObjectIds.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: resource_id
          in: query
          required: false
          description: Filter categories by resource. Accepts valid MongoDB ObjectId.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Enterprise Services
      summary: Create enterprise service category
      description: Create a new enterprise service category.
      operationId: postV1EnterpriseServicesCategories
      responses:
        '201':
          description: >-
            Creates new enterprise service category and returns created category
            record with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1EnterpriseServicesCategoriesRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprise-services/categories/{categoryId}:
    delete:
      tags:
        - Enterprise Services
      summary: Delete enterprise service category
      description: >-
        The URL parameter ":categoryId" can be used in two ways: - use the
        unique ID of the service category assigned by TIMIFY ("categoryId"). In
        this case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this service category. In this case, you
        need to add the parameter "external" ( for ex.: */?external=1*) so the
        Developer API will search by your "externalId" and not by "categoryId"
        assigned by TIMIFY You can add "externalId" to the service with the
        Developer API endpoints *POST /services/caetgories* and *PATCH
        /service/categories/:categoryId*
      operationId: deleteV1EnterpriseServicesCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Confirms deletion of the enterprise service category and returns
            confirmation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Enterprise Services
      summary: Fetch enterprise service category
      description: >-
        The URL parameter "categoryId" can be used in two ways: - use the unique
        ID of the service category assigned by TIMIFY ("categoryId"). In this
        case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this service category. In this case, you
        need to add the parameter "external" ( for ex.: */?external=1*) so the
        Developer API will search by your "externalId" and not by "categoryId"
        assigned by TIMIFY You can add "externalId" to the service category with
        the Developer API endpoints *POST /services/categories* and *PATCH
        /services/categories/:categoryId*
      operationId: getV1EnterpriseServicesCategoriesByCategoryid
      responses:
        '200':
          description: Returns the specified enterprise service category with its metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Enterprise Services
      summary: Update enterprise service category
      description: Update an enterprise service category.
      operationId: patchV1EnterpriseServicesCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Updates the enterprise service category and returns the updated
            category record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PatchV1EnterpriseServicesCategoriesByCategoryidRequest
      security:
        - BearerAuth: []
  /v1/enterprise-services/{serviceId}:
    delete:
      tags:
        - Enterprise Services
      summary: Delete enterprise service
      description: >-
        The URL parameter "serviceId" can be used in two ways: - use the unique
        ID of the service assigned by TIMIFY ("serviceId"). In this case, you
        don't need the QUERY parameter "external" - use the "externalId" that
        you added to this service. In this case, you need to add the parameter
        "external" ( for ex.: */?external=1*) so the Developer API will search
        by your "externalId" and not by "serviceId" assigned by TIMIFY You can
        add "externalId" to the service with the Developer API endpoints *POST
        /services* and *PATCH service/:serviceId*
      operationId: deleteV1EnterpriseServicesByServiceid
      responses:
        '200':
          description: >-
            Confirms deletion of the enterprise service and returns the deleted
            service record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: serviceId
          in: path
          required: true
          description: Serviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Enterprise Services
      summary: Fetch enterprise service
      description: >-
        The URL parameter ":serviceId" can be used in two ways: - use the unique
        ID of the service assigned by TIMIFY ("serviceId"). In this case, you
        don't need the QUERY parameter "external" - use the "externalId" that
        you added to this service. In this case, you need to add the parameter
        "external" ( for ex.: */?external=1*) so the Developer API will search
        by your "externalId" and not by "serviceId" assigned by TIMIFY You can
        add "externalId" to the service with the Developer API endpoints *POST
        /services* and *PATCH services/:serviceId* When the developer wants to
        include booking limit suggestions in the response, the booking
        limitation params needs to be be included in the query, only the
        `start_date` is mandatory ``` ?start_date=2019-02-23
        11:30&event_id=645515845089ba22acfa569e&durations_pattern=5&duration_before=30&duration_after=30
        ```
      operationId: getV1EnterpriseServicesByServiceid
      responses:
        '200':
          description: >-
            Returns the specified enterprise service with complete details and
            metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: serviceId
          in: path
          required: true
          description: Serviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - name: start_date
          in: query
          required: false
          description: >-
            Start date for availability checks in booking limit suggestions.
            Format: YYYY-MM-DD HH:mm.
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2026-03-02 09:00
        - name: event_id
          in: query
          required: false
          description: Filter service details by event. Accepts valid MongoDB ObjectId.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: durations_pattern[]
          in: query
          required: false
          description: >-
            Duration availability pattern. Must be divisible by 5 (minutes).
            Include multiple times for varied availability.
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 20
        - name: duration_before
          in: query
          required: false
          description: Buffer time before service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - name: duration_after
          in: query
          required: false
          description: Buffer time after service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - name: with_full_attributes
          in: query
          required: false
          description: >-
            Include complete service attributes in response. Set to true for
            detailed service information.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Enterprise Services
      summary: Update enterprise service
      description: >-
        The URL parameter "serviceId" can be used in two ways: - use the unique
        ID of the service assigned by TIMIFY ("serviceId"). In this case, you
        don't need the QUERY parameter "external" - use the "externalId" that
        you added to this service. In this case, you need to add the parameter
        "external" ( for ex.: */?external=1*) so the Developer API will search
        by your "externalId" and not by "serviceId" assigned by TIMIFY You can
        add "externalId" to the service with the Developer API
      operationId: patchV1EnterpriseServicesByServiceid
      responses:
        '200':
          description: >-
            Updates the enterprise service and returns the updated service
            record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: serviceId
          in: path
          required: true
          description: Serviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - name: start_date
          in: query
          required: false
          description: 'Start date for service availability. Format: YYYY-MM-DD HH:mm.'
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2026-03-02 09:00
        - name: event_id
          in: query
          required: false
          description: Associate service with event. Accepts valid MongoDB ObjectId.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: durations_pattern[]
          in: query
          required: false
          description: >-
            Duration availability pattern. Must be divisible by 5 (minutes).
            Include multiple times for varied availability.
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 20
        - name: duration_before
          in: query
          required: false
          description: Buffer time before service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - name: duration_after
          in: query
          required: false
          description: Buffer time after service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1EnterpriseServicesByServiceidRequest'
      security:
        - BearerAuth: []
  /v1/enterprise-services/{serviceId}/reset:
    get:
      tags:
        - Enterprise Services
      summary: Reset enterprise service
      description: >-
        In the event a branch has update the local service parameters the owner
        of the Enterprise can reset the local service to the global service
        parameters. The Enterprise owner or manager can update all or selected
        service attributes.
      operationId: getV1EnterpriseServicesByServiceidReset
      responses:
        '200':
          description: Returns reset information for the specified enterprise service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: serviceId
          in: path
          required: true
          description: Serviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: company_ids
          in: query
          required: false
          description: Company IDs to reset for. Comma-separated list of valid MongoDB IDs.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: keys
          in: query
          required: false
          description: >-
            Attribute keys to reset (e.g., name, description, duration).
            Comma-separated list of attribute names.
          schema:
            type: string
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/services:
    get:
      tags:
        - Services
      summary: List services
      description: >-
        This endpoint retrieves all the services. When the developer wants to
        include booking limit suggestions in the response, the booking
        limitation params needs to be be included in the query, only the
        `start_date` is mandatory ``` ?start_date=2019-02-23
        11:30&event_id=645515845089ba22acfa569e&durations_pattern=5&duration_before=30&duration_after=30
        ```
      operationId: getV1Services
      responses:
        '200':
          description: >-
            Returns paginated list of company-level services with optional
            booking limit suggestions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34cd
                    externalId: SVC-CONSULTATION-001
                    name: Consultation
                    description: 30-minute one-on-one consultation session
                    duration: 30
                    durationBefore: 10
                    durationAfter: 5
                    price: 99.99
                    isBookable: true
                    isCourse: false
                    color: '#1976d2'
                    categoryId: 646377d319354093d997f819
                    categoryName: Services
                    resourceIds:
                      - 62ee11a91d66269c365407b1
                      - 62ee11a91d66269c365407b2
                    maxParticipants: 1
                    maxWaitlistParticipants: 5
                    createdAt: '2024-01-15T10:30:00Z'
                    updatedAt: '2024-02-20T14:45:30Z'
                    ts: 1708430730
                  - id: 65f4c840b6f1a10012ab34ce
                    externalId: SVC-MASSAGE-001
                    name: Swedish Massage
                    description: Full body Swedish massage (60 minutes)
                    duration: 60
                    durationBefore: 15
                    durationAfter: 10
                    price: 149.99
                    isBookable: true
                    isCourse: false
                    color: '#ff9800'
                    categoryId: 646377d319354093d997f81a
                    categoryName: Wellness
                    resourceIds:
                      - 62ee11a91d66269c365407b3
                    maxParticipants: 1
                    maxWaitlistParticipants: 3
                    createdAt: '2024-01-20T14:30:00Z'
                    updatedAt: '2024-02-15T11:00:00Z'
                    ts: 1708058400
                total: 42
                meta:
                  page: 1
                  limit: 20
                  totalItems: 42
                  totalPages: 3
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: is_bookable
          in: query
          required: false
          description: >-
            Filter results to only bookable services. Set to true to exclude
            non-bookable services.
          schema:
            type: boolean
          example: true
        - name: category_id
          in: query
          required: false
          description: >-
            Filter services by category. Accepts valid MongoDB ObjectId of a
            service category.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: resource_id
          in: query
          required: false
          description: >-
            Filter services assigned to a specific resource. Accepts valid
            MongoDB ObjectId.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: resource_category_id
          in: query
          required: false
          description: >-
            Filter services by resource category. Accepts valid MongoDB ObjectId
            of a resource category.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: ids
          in: query
          required: false
          description: >-
            Filter results by service IDs. Accepts array of valid MongoDB
            ObjectIds.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: external_ids
          in: query
          required: false
          description: >-
            Filter services by external IDs. Accepts array of external ID
            strings.
          schema:
            type: array
            items:
              type: string
              example: EXT-SERVICE-001
            minItems: 1
          example:
            - EXT-SERVICE-001
        - name: is_stalled
          in: query
          required: false
          description: >-
            Filter stalled services. Set to true to show only temporarily paused
            services.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - name: sort_type
          in: query
          required: false
          description: >-
            Sort direction. Accepts "asc" (ascending) or "desc" (descending).
            Default: asc.
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: sort
          in: query
          required: false
          description: Sort results by field. Typically "name" or "createdAt".
          schema:
            type: string
        - name: start_date
          in: query
          required: false
          description: >-
            Start date for availability checks in booking limit suggestions.
            Format: YYYY-MM-DD HH:mm.
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2026-03-02 09:00
        - name: event_id
          in: query
          required: false
          description: Filter services by event. Accepts valid MongoDB ObjectId.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: durations_pattern[]
          in: query
          required: false
          description: >-
            Duration availability pattern. Must be divisible by 5 (minutes).
            Include multiple times for varied availability.
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 20
        - name: duration_before
          in: query
          required: false
          description: Buffer time before service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - name: duration_after
          in: query
          required: false
          description: Buffer time after service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - name: with_full_attributes
          in: query
          required: false
          description: >-
            Include complete service attributes in response. Set to true for
            detailed service information.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Services
      summary: Create service
      description: >-
        This endpoint creates a new service. All appointments, for this service,
        is saved as a single interval. The service can optionally be limited to
        specific hours of the day. The calendar attribute needs to be present.
        The example following example limits the service to Mondays, Tuesdays
        and Fridays from 10:00 to 12:00 in the timezone "LATIN_AMERICA" ```
        "calendar": { "timezone": "America/Bogota", "region": "LATIN_AMERICA",
        "booking_weekly_allowance_plan": [ {}, { "isActive": true, "times": [ {
        "begin": "10:00", "end": "12:00" } ] }, {}, {}, {}, { "isActive": true,
        "times": [ { "begin": "10:00", "end": "12:00" } ] }, {} ] } ```
      operationId: postV1Services
      responses:
        '201':
          description: >-
            Creates new company-level service and returns created service record
            with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: SVC-CONSULTATION-001
                  name: Consultation
                  description: 30-minute one-on-one consultation session
                  duration: 30
                  durationBefore: 10
                  durationAfter: 5
                  price: 99.99
                  isBookable: true
                  isCourse: false
                  color: '#1976d2'
                  categoryId: 646377d319354093d997f819
                  categoryName: Services
                  resourceIds:
                    - 62ee11a91d66269c365407b1
                  maxParticipants: 1
                  maxWaitlistParticipants: 5
                  createdAt: '2024-03-01T10:30:00Z'
                  updatedAt: '2024-03-01T10:30:00Z'
                  ts: 1709283000
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: start_date
          in: query
          required: false
          description: 'Start date for service availability. Format: YYYY-MM-DD HH:mm.'
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2026-03-02 09:00
        - name: event_id
          in: query
          required: false
          description: Associate service with event. Accepts valid MongoDB ObjectId.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: durations_pattern[]
          in: query
          required: false
          description: >-
            Duration availability pattern. Must be divisible by 5 (minutes).
            Include multiple times for varied availability.
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 20
        - name: duration_before
          in: query
          required: false
          description: Buffer time before service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - name: duration_after
          in: query
          required: false
          description: Buffer time after service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ServicesRequest'
      security:
        - BearerAuth: []
  /v1/services/categories:
    get:
      tags:
        - Services
      summary: List service categories
      description: List service categories.
      operationId: getV1ServicesCategories
      responses:
        '200':
          description: Returns paginated list of company-level service categories.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: >-
            Filter results by category IDs. Accepts array of valid MongoDB
            ObjectIds.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: resource_id
          in: query
          required: false
          description: Filter categories by resource. Accepts valid MongoDB ObjectId.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Services
      summary: Create service category
      description: Create a new service category.
      operationId: postV1ServicesCategories
      responses:
        '201':
          description: >-
            Creates new company-level service category and returns created
            category record with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1ServicesCategoriesRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/services/categories/{categoryId}:
    delete:
      tags:
        - Services
      summary: Delete service category
      description: >-
        The URL parameter ":categoryId" can be used in two ways: - use the
        unique ID of the service category assigned by TIMIFY ("categoryId"). In
        this case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this service category. In this case, you
        need to add the parameter "external" ( for ex.: */?external=1*) so the
        Developer API will search by your "externalId" and not by "categoryId"
        assigned by TIMIFY You can add "externalId" to the service with the
        Developer API endpoints *POST /services/caetgories* and *PATCH
        /service/categories/:categoryId*
      operationId: deleteV1ServicesCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Confirms deletion of the company-level service category and returns
            confirmation response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Services
      summary: Fetch service category
      description: >-
        The URL parameter "categoryId" can be used in two ways: - use the unique
        ID of the service category assigned by TIMIFY ("categoryId"). In this
        case, you don't need the QUERY parameter "external" - use the
        "externalId" that you added to this service category. In this case, you
        need to add the parameter "external" ( for ex.: */?external=1*) so the
        Developer API will search by your "externalId" and not by "categoryId"
        assigned by TIMIFY You can add "externalId" to the service category with
        the Developer API endpoints *POST /services/categories* and *PATCH
        /services/categories/:categoryId*
      operationId: getV1ServicesCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Returns the specified company-level service category with its
            metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Services
      summary: Update service category
      description: Update a service category.
      operationId: patchV1ServicesCategoriesByCategoryid
      responses:
        '200':
          description: >-
            Updates the company-level service category and returns the updated
            category record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: categoryId
          in: path
          required: true
          description: Categoryid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/PatchV1ServicesCategoriesByCategoryidRequest
      security:
        - BearerAuth: []
  /v1/services/{serviceId}:
    delete:
      tags:
        - Services
      summary: Delete service by ID
      description: >-
        The URL parameter "serviceId" can be used in two ways: - use the unique
        ID of the service assigned by TIMIFY ("serviceId"). In this case, you
        don't need the QUERY parameter "external" - use the "externalId" that
        you added to this service. In this case, you need to add the parameter
        "external" ( for ex.: */?external=1*) so the Developer API will search
        by your "externalId" and not by "serviceId" assigned by TIMIFY You can
        add "externalId" to the service with the Developer API endpoints *POST
        /services* and *PATCH service/:serviceId*
      operationId: deleteV1ServicesByServiceid
      responses:
        '200':
          description: >-
            Confirms deletion of the company-level service and returns the
            deleted service record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: serviceId
          in: path
          required: true
          description: Serviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Services
      summary: Fetch service
      description: >-
        The URL parameter ":serviceId" can be used in two ways: - use the unique
        ID of the service assigned by TIMIFY ("serviceId"). In this case, you
        don't need the QUERY parameter "external" - use the "externalId" that
        you added to this service. In this case, you need to add the parameter
        "external" ( for ex.: */?external=1*) so the Developer API will search
        by your "externalId" and not by "serviceId" assigned by TIMIFY You can
        add "externalId" to the service with the Developer API endpoints *POST
        /services* and *PATCH services/:serviceId* When the developer wants to
        include booking limit suggestions in the response, the booking
        limitation params needs to be be included in the query, only the
        `start_date` is mandatory ``` ?start_date=2019-02-23
        11:30&event_id=645515845089ba22acfa569e&durations_pattern=5&duration_before=30&duration_after=30
        ```
      operationId: getV1ServicesByServiceid
      responses:
        '200':
          description: >-
            Returns the specified company-level service with complete details
            and metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: serviceId
          in: path
          required: true
          description: Serviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - name: start_date
          in: query
          required: false
          description: >-
            Start date for availability checks in booking limit suggestions.
            Format: YYYY-MM-DD HH:mm.
          schema:
            type: string
            pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2026-03-02 09:00
        - name: event_id
          in: query
          required: false
          description: Filter service details by event. Accepts valid MongoDB ObjectId.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: durations_pattern[]
          in: query
          required: false
          description: >-
            Duration availability pattern. Must be divisible by 5 (minutes).
            Include multiple times for varied availability.
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 20
        - name: duration_before
          in: query
          required: false
          description: Buffer time before service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - name: duration_after
          in: query
          required: false
          description: Buffer time after service. Must be divisible by 5 (minutes).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 30
        - name: with_full_attributes
          in: query
          required: false
          description: >-
            Include complete service attributes in response. Set to true for
            detailed service information.
          schema:
            type: boolean
          example: true
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Services
      summary: Update service
      description: >-
        The service can optionally be limited to specific hours of the day. The
        calendar attribute needs to be present. The example following example
        limits the service to Mondays, Tuesdays and Fridays from 10:00 to 12:00
        in the timezone "LATIN_AMERICA" ``` { "calendar": { "timezone":
        "America/Bogota", "region": "LATIN_AMERICA",
        "booking_weekly_allowance_plan": [ {}, { "isActive": true, "times": [ {
        "begin": "10:00", "end": "12:00" } ] }, {}, {}, {}, { "isActive": true,
        "times": [ { "begin": "10:00", "end": "12:00" } ] }, {} ],
        "working_weekly_allowance_plan": [ {}, { "isActive": true, "times": [ {
        "begin": "10:00", "end": "12:00" } ] }, {}, {}, {}, { "isActive": true,
        "times": [ { "begin": "10:00", "end": "12:00" } ] }, {} ] } } ```
      operationId: patchV1ServicesByServiceid
      responses:
        '200':
          description: >-
            Updates the company-level service and returns the updated service
            record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: serviceId
          in: path
          required: true
          description: Serviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: external
          in: query
          required: false
          description: >-
            When set to `1`, the path ID parameter is treated as an `externalId`
            instead of TIMIFY's internal MongoDB ID.
          schema:
            type: boolean
          example: true
        - name: start_date
          in: query
          required: false
          description: >-
            Filter services by start date before applying the update (format:
            YYYY-MM-DD).
          schema:
            type: string
            format: date
          example: '2026-03-02'
        - name: event_id
          in: query
          required: false
          description: >-
            Filter services by event ID before applying the update. Must be a
            valid MongoDB ID.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: durations_pattern[]
          in: query
          required: false
          description: >-
            Filter services by duration patterns in minutes (must be divisible
            by 5).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 20
        - name: duration_before
          in: query
          required: false
          description: >-
            Filter services by duration before buffer in minutes (must be
            divisible by 5).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 20
        - name: duration_after
          in: query
          required: false
          description: >-
            Filter services by duration after buffer in minutes (must be
            divisible by 5).
          schema:
            type: integer
            minimum: 0
            multipleOf: 5
          example: 20
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1ServicesByServiceidRequest'
      security:
        - BearerAuth: []
  /v1/services/{serviceId}/booking-limit:
    get:
      tags:
        - Services
      summary: Fetch service booking limit config
      description: Retrieve the booking limit configuration for a service.
      operationId: getV1ServicesByServiceidBookingLimit
      responses:
        '200':
          description: >-
            Returns booking limit information for the specified company-level
            service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: serviceId
          in: path
          required: true
          description: Serviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: resource_ids
          in: query
          required: false
          description: >-
            Filter booking limits by specific resource IDs. Comma-separated list
            of valid MongoDB IDs.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: days
          in: query
          required: false
          description: 'Filter booking limits for specific dates (format: YYYY-MM-DD).'
          schema:
            type: array
            items:
              type: string
              format: date
              example: '2026-03-02'
            minItems: 1
          example:
            - '2026-03-02'
        - name: days_of_week
          in: query
          required: false
          description: Filter booking limits by day of week (0-6, where 0=Sunday).
          schema:
            type: string
        - name: keys
          in: query
          required: false
          description: Filter booking limits by specific attribute keys.
          schema:
            type: string
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/services/{serviceId}/reset:
    get:
      tags:
        - Services
      summary: Reset service
      description: >-
        When the branch owner updates service attributes, they have the option
        to reset it to the global service attributes. All or selected service
        attributes can be updated
      operationId: getV1ServicesByServiceidReset
      responses:
        '200':
          description: Returns reset information for the specified company-level service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: serviceId
          in: path
          required: true
          description: Serviceid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - name: keys
          in: query
          required: false
          description: >-
            Attribute keys to reset (e.g., name, description, duration).
            Comma-separated list of attribute names.
          schema:
            type: string
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/enterprise/statistics/resources:
    get:
      tags:
        - Statistics
      summary: Fetch resources statistics
      description: Return resource utilization statistics at the enterprise level.
      operationId: getV1EnterpriseStatisticsResources
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: month
          in: query
          required: false
          description: 'Filter statistics by month (format: MM or 1-12).'
          schema:
            type: string
        - name: year
          in: query
          required: false
          description: 'Filter statistics by year (format: YYYY).'
          schema:
            type: string
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/branch-tags:
    get:
      tags:
        - Tags
      summary: List enterprise branch tags
      description: Get all tags associated to branches defined in the Branch Manager.
      operationId: getV1BranchTags
      responses:
        '200':
          description: >-
            Returns paginated list of branch tags defined in the Branch Manager
            with their associated metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34cd
                    externalId: BTAG-MAIN
                    name: Main Branch
                    orderIndex: 0
                    createdAt: '2024-01-15T10:30:00Z'
                    updatedAt: '2024-02-20T14:45:30Z'
                    ts: 1708430730
                  - id: 65f4c840b6f1a10012ab34ce
                    externalId: BTAG-SECONDARY
                    name: Secondary Branch
                    orderIndex: 1
                    createdAt: '2024-01-20T14:30:00Z'
                    updatedAt: '2024-02-15T11:00:00Z'
                    ts: 1708058400
                total: 4
                meta:
                  page: 1
                  limit: 20
                  totalItems: 4
                  totalPages: 1
                status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Tags
      summary: Create enterprise branch tag
      description: >-
        Create a tag that can then be applied to one or more branches belonging
        to the same enterprise account.
      operationId: postV1BranchTags
      responses:
        '201':
          description: >-
            Creates new branch tag and returns created record with assigned ID
            that can be applied to branches.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: BTAG-MAIN
                  name: Main Branch
                  orderIndex: 0
                  createdAt: '2024-03-01T10:30:00Z'
                  updatedAt: '2024-03-01T10:30:00Z'
                  ts: 1709283000
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1BranchTagsRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/branch-tags/{tagId}:
    delete:
      tags:
        - Tags
      summary: Delete resource
      description: Delete a branch tag.
      operationId: deleteV1BranchTagsByTagid
      responses:
        '200':
          description: >-
            Confirms deletion of the branch tag and returns the deleted tag
            record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: tagId
          in: path
          required: true
          description: Tagid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Tags
      summary: Get resource
      description: Fetch a single branch tag by ID.
      operationId: getV1BranchTagsByTagid
      responses:
        '200':
          description: Returns the specified branch tag with its metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: BTAG-MAIN
                  name: Main Branch
                  orderIndex: 0
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: '2024-02-20T14:45:30Z'
                  ts: 1708430730
                status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: tagId
          in: path
          required: true
          description: Tagid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Tags
      summary: Patch resource
      description: Update a branch tag.
      operationId: patchV1BranchTagsByTagid
      responses:
        '200':
          description: Updates the branch tag and returns the updated tag record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  externalId: BTAG-MAIN
                  name: Main Branch
                  orderIndex: 0
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: '2024-03-01T15:20:00Z'
                  ts: 1709297400
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: tagId
          in: path
          required: true
          description: Tagid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1BranchTagsByTagidRequest'
      security:
        - BearerAuth: []
  /v1/enterprise-tags:
    get:
      tags:
        - Tags
      summary: List enterprise tags
      description: List tags at the enterprise level.
      operationId: getV1EnterpriseTags
      responses:
        '200':
          description: >-
            Returns paginated list of enterprise-level tags with filtering
            applied.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34cd
                    globalId: internal-id
                    externalId: TAG-VIP
                    name: VIP Customer
                    color: '#FF5733'
                    note: Important customer
                    orderIndex: 0
                    isForAppointments: true
                    isForCustomers: true
                    eventsCount: 42
                    customersCount: 15
                    createdAt: '2024-01-15T10:30:00Z'
                    updatedAt: '2024-02-20T14:45:30Z'
                    ts: 1708430730
                  - id: 65f4c840b6f1a10012ab34ce
                    globalId: internal-id-2
                    externalId: TAG-PREMIUM
                    name: Premium Member
                    color: '#FFD700'
                    note: Premium subscription
                    orderIndex: 1
                    isForAppointments: false
                    isForCustomers: true
                    eventsCount: 28
                    customersCount: 8
                    createdAt: '2024-01-20T14:30:00Z'
                    updatedAt: '2024-02-15T11:00:00Z'
                    ts: 1708058400
                total: 8
                meta:
                  page: 1
                  limit: 20
                  totalItems: 8
                  totalPages: 1
                status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: Filter results by tag IDs. Accepts array of valid MongoDB ObjectIds.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: for_customers
          in: query
          required: false
          description: >-
            Filter tags applicable to customers. Set to true to show only
            customer-applicable tags.
          schema:
            type: boolean
        - name: for_appointments
          in: query
          required: false
          description: >-
            Filter tags applicable to appointments. Set to true to show only
            appointment-applicable tags.
          schema:
            type: boolean
        - name: external_id
          in: query
          required: false
          description: Filter tags by external ID. Accepts external tag identifier.
          schema:
            type: string
          example: EXT-TAG-001
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Tags
      summary: Create enterprise tag
      description: Create a new enterprise tag.
      operationId: postV1EnterpriseTags
      responses:
        '201':
          description: >-
            Creates new enterprise tag and returns created tag record with
            assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  globalId: internal-id
                  externalId: TAG-VIP
                  name: VIP Customer
                  color: '#FF5733'
                  note: Important customer
                  orderIndex: 0
                  isForAppointments: true
                  isForCustomers: true
                  eventsCount: 0
                  customersCount: 0
                  createdAt: '2024-03-01T10:30:00Z'
                  updatedAt: '2024-03-01T10:30:00Z'
                  ts: 1709283000
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1EnterpriseTagsRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/enterprise-tags/{tagId}:
    delete:
      tags:
        - Tags
      summary: Delete enterprise tag
      description: Delete an enterprise tag.
      operationId: deleteV1EnterpriseTagsByTagid
      responses:
        '200':
          description: >-
            Confirms deletion of the enterprise tag and returns the deleted tag
            record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: tagId
          in: path
          required: true
          description: Tagid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Tags
      summary: Fetch enterprise tag
      description: Fetch a single enterprise tag.
      operationId: getV1EnterpriseTagsByTagid
      responses:
        '200':
          description: Returns the specified enterprise tag with its metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  globalId: internal-id
                  externalId: TAG-VIP
                  name: VIP Customer
                  color: '#FF5733'
                  note: Important customer
                  orderIndex: 0
                  isForAppointments: true
                  isForCustomers: true
                  eventsCount: 42
                  customersCount: 15
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: '2024-02-20T14:45:30Z'
                  ts: 1708430730
                status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: tagId
          in: path
          required: true
          description: Tagid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Tags
      summary: Update enterprise tag
      description: Update an enterprise tag.
      operationId: patchV1EnterpriseTagsByTagid
      responses:
        '200':
          description: Updates the enterprise tag and returns the updated tag record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  globalId: internal-id
                  externalId: TAG-VIP
                  name: VIP Customer
                  color: '#FF5733'
                  note: Important customer (Updated)
                  orderIndex: 0
                  isForAppointments: true
                  isForCustomers: true
                  eventsCount: 42
                  customersCount: 15
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: '2024-03-01T15:20:00Z'
                  ts: 1709297400
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: tagId
          in: path
          required: true
          description: Tagid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1EnterpriseTagsByTagidRequest'
      security:
        - BearerAuth: []
  /v1/tags:
    get:
      tags:
        - Tags
      summary: List tags
      description: >-
        Returns all tags for the company. Tags can be applied to customers
        and/or appointments for classification and filtering.
      operationId: getV1Tags
      responses:
        '200':
          description: >-
            Returns all company-level tags that can be applied to customers and
            appointments.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Tag'
                  total:
                    type: integer
                    example: 8
                  status:
                    type: integer
                    example: 1
              example:
                data:
                  - id: 65f4c840b6f1a10012ab34cd
                    globalId: internal-id
                    externalId: TAG-VIP
                    name: VIP Customer
                    color: '#FF5733'
                    note: Important customer
                    orderIndex: 0
                    isForAppointments: true
                    isForCustomers: true
                    eventsCount: 42
                    customersCount: 15
                    createdAt: '2024-01-15T10:30:00Z'
                    updatedAt: '2024-02-20T14:45:30Z'
                    ts: 1708430730
                  - id: 65f4c840b6f1a10012ab34ce
                    globalId: internal-id-2
                    externalId: TAG-PREMIUM
                    name: Premium Member
                    color: '#FFD700'
                    note: Premium subscription
                    orderIndex: 1
                    isForAppointments: false
                    isForCustomers: true
                    eventsCount: 28
                    customersCount: 8
                    createdAt: '2024-01-20T14:30:00Z'
                    updatedAt: '2024-02-15T11:00:00Z'
                    ts: 1708058400
                  - id: 65f4c840b6f1a10012ab34cf
                    globalId: internal-id-3
                    externalId: TAG-BLOCKED
                    name: Blocked
                    color: '#FF0000'
                    note: Blocked from booking
                    orderIndex: 2
                    isForAppointments: true
                    isForCustomers: true
                    eventsCount: 5
                    customersCount: 3
                    createdAt: '2024-02-01T09:15:00Z'
                    updatedAt: '2024-02-25T15:45:00Z'
                    ts: 1708951500
                total: 8
                status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: ids
          in: query
          required: false
          description: Filter results by tag IDs. Accepts array of valid MongoDB ObjectIds.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: for_customers
          in: query
          required: false
          description: >-
            Filter tags applicable to customers. Set to true to show only
            customer-applicable tags.
          schema:
            type: boolean
        - name: for_appointments
          in: query
          required: false
          description: >-
            Filter tags applicable to appointments. Set to true to show only
            appointment-applicable tags.
          schema:
            type: boolean
        - name: global_id
          in: query
          required: false
          description: Filter tags by global ID. Accepts valid MongoDB ObjectId.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Tags
      summary: Create tag
      description: >-
        Create a new tag. Use `for_customers` and `for_events` to control where
        the tag can be applied.
      operationId: postV1Tags
      responses:
        '201':
          description: >-
            Creates new company-level tag and returns created tag record with
            assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  globalId: internal-id
                  externalId: TAG-VIP
                  name: VIP Customer
                  color: '#FF5733'
                  note: Important customer
                  orderIndex: 0
                  isForAppointments: true
                  isForCustomers: true
                  eventsCount: 0
                  customersCount: 0
                  createdAt: '2024-03-01T10:30:00Z'
                  updatedAt: '2024-03-01T10:30:00Z'
                  ts: 1709283000
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1TagsRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/tags/{tagId}:
    delete:
      tags:
        - Tags
      summary: Delete tag by ID
      description: Permanently delete a tag by its ID.
      operationId: deleteV1TagsByTagid
      responses:
        '200':
          description: >-
            Confirms deletion of the company-level tag and returns the deleted
            tag record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: tagId
          in: path
          required: true
          description: Tagid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Tags
      summary: Fetch tag
      description: Retrieve a single tag by its ID.
      operationId: getV1TagsByTagid
      responses:
        '200':
          description: Returns the specified company-level tag with its metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  globalId: internal-id
                  externalId: TAG-VIP
                  name: VIP Customer
                  color: '#FF5733'
                  note: Important customer
                  orderIndex: 0
                  isForAppointments: true
                  isForCustomers: true
                  eventsCount: 42
                  customersCount: 15
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: '2024-02-20T14:45:30Z'
                  ts: 1708430730
                status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: tagId
          in: path
          required: true
          description: Tagid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Tags
      summary: Update tag
      description: >-
        Update an existing tag by ID. Supports externalId lookup via
        `?external=1`.
      operationId: patchV1TagsByTagid
      responses:
        '200':
          description: Updates the company-level tag and returns the updated tag record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              example:
                data:
                  id: 65f4c840b6f1a10012ab34cd
                  globalId: internal-id
                  externalId: TAG-VIP
                  name: VIP Customer
                  color: '#FF5733'
                  note: Important customer (Updated)
                  orderIndex: 0
                  isForAppointments: true
                  isForCustomers: true
                  eventsCount: 42
                  customersCount: 15
                  createdAt: '2024-01-15T10:30:00Z'
                  updatedAt: '2024-03-01T15:20:00Z'
                  ts: 1709297400
                status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: tagId
          in: path
          required: true
          description: Tagid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1TagsByTagidRequest'
      security:
        - BearerAuth: []
  /v1/timeshifts:
    get:
      tags:
        - Timeshifts
      summary: List timeshifts
      description: >-
        Filter timeshifts: - By resource ids or external ids - For a specific
        time interval use _from_ and _to_ parameters - For specific days use
        _day[]_ parameter, day format is YYYY-MM-DD These filters are mutually
        exclusive and cannot be used at the same time, if fields _from_ and _to_
        are sent, _day[]_ will be ignored
      operationId: getV1Timeshifts
      responses:
        '200':
          description: >-
            Returns paginated list of time shifts filtered by date range and/or
            resources with their details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              examples:
                success:
                  summary: Timeshifts list
                  value:
                    data:
                      - id: 65f4c840b6f1a10012ab34cd
                        resourceId: 62ee11a91d66269c365407b1
                        resourceName: John Smith
                        days:
                          - '2024-03-18'
                          - '2024-03-19'
                        workingTimes:
                          - begin: '09:00'
                            end: '17:00'
                        bookingTimes:
                          - begin: '09:00'
                            end: '17:00'
                        createdAt: '2024-03-07T10:30:00Z'
                        updatedAt: '2024-03-07T10:30:00Z'
                        ts: 1709823000
                      - id: 65f5d951c7g2b20123bc45df
                        resourceId: 62ee11a91d66269c365407b2
                        resourceName: Jane Doe
                        days:
                          - '2024-03-20'
                        denialReason: VACATION
                        denialTimes:
                          - begin: '00:00'
                            end: '24:00'
                        createdAt: '2024-03-05T14:15:00Z'
                        updatedAt: '2024-03-05T14:15:00Z'
                        ts: 1709658900
                    total: 2
                    meta:
                      page: 1
                      limit: 10
                      totalItems: 2
                      totalPages: 1
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: from
          in: query
          required: false
          description: >-
            Filter timeshifts from start date (format: YYYY-MM-DD). Mutually
            exclusive with day parameter.
          schema:
            type: string
        - name: to
          in: query
          required: false
          description: >-
            Filter timeshifts to end date (format: YYYY-MM-DD). Mutually
            exclusive with day parameter.
          schema:
            type: string
        - name: day
          in: query
          required: false
          description: >-
            Filter timeshifts for a specific day (format: YYYY-MM-DD). Mutually
            exclusive with from/to parameters.
          schema:
            type: string
        - name: resource_ids
          in: query
          required: false
          description: >-
            Filter timeshifts by resource IDs. Comma-separated list of valid
            MongoDB IDs.
          schema:
            type: array
            items:
              type: string
              pattern: ^[0-9a-f]{24}$
              example: 65f4c840b6f1a10012ab34cd
            minItems: 1
          example:
            - 65f4c840b6f1a10012ab34cd
        - name: resource_external_ids
          in: query
          required: false
          description: >-
            Filter timeshifts by resource external IDs. Comma-separated list of
            external identifiers.
          schema:
            type: array
            items:
              type: string
              example: ext-resource-001
            minItems: 1
          example:
            - ext-resource-001
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    post:
      tags:
        - Timeshifts
      summary: Create timeshift
      description: >-
        This endpoint creates shifts for a resource on a selected date. It
        enables the user to create work and booking shifts. There is also an
        option to create non-workable shifts, for example "VACATION", "SICK" or
        "BLOCKER" shifts If you select the "BLOCKER" as the _denial_reason_,
        parameters _working_times_ and _booking_times_ will be ignored Examples:
        - Work shift: ``` { "from": "2023-10-02", "to": "2023-10-02",
        "resource_id": "64759027a6f9909999a59431", "working_times": [ { "begin":
        "08:00", "end": "14:40" }, { "begin": "15:00", "end": "18:00" } ],
        "booking_times": [ { "begin": "08:00", "end": "14:40" }, { "begin":
        "15:00", "end": "18:00" } ] } ``` - Vacation: ``` { "denial_reason":
        "VACATION", "from": "2020-10-20", "to": "2020-10-22", "resource_id":
        "5f61c6381a34817e5c7fa220", "denial_times": [ { "begin": "00:00", "end":
        "24:00" } ] } ``` - Sick: ``` { "denial_reason": "SICK", "from":
        "2020-10-20", "to": "2020-10-22", "resource_id":
        "5f61c6381a34817e5c7fa220", "denial_times": [ { "begin": "00:00", "end":
        "24:00" } ] } ``` - Blocker: _working_times_ and _booking_times_
        parameters are ignored ``` { "denial_reason": "BLOCKER", "from":
        "2020-10-20", "to": "2020-10-22", "resource_id":
        "5f61c6381a34817e5c7fa220", "denial_times": [ { "begin": "00:00", "end":
        "24:00" } ] } ```
      operationId: postV1Timeshifts
      responses:
        '201':
          description: Creates new time shift and returns created record with assigned ID.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Work shift created
                  value:
                    data:
                      id: 65f6e062d8h3c31234cd56eg
                      resourceId: 62ee11a91d66269c365407b1
                      resourceName: John Smith
                      days:
                        - '2024-03-18'
                      workingTimes:
                        - begin: '09:00'
                          end: '17:00'
                      bookingTimes:
                        - begin: '09:00'
                          end: '17:00'
                      shiftType: WORKING
                      createdAt: '2024-03-07T10:30:00Z'
                      updatedAt: '2024-03-07T10:30:00Z'
                      ts: 1709823000
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1TimeshiftsRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/timeshifts/import/bulk:
    post:
      tags:
        - Timeshifts
      summary: Import or update timeshift
      description: >-
        This endpoint bulk imports shifts for users. It enables the user to
        create work and booking shifts. There is also an option to create
        non-workable shifts, for example "VACATION", "SICK" or "BLOCKER" shifts
        If you select the "BLOCKER" as the _denialReason_, parameters
        _workingTimes_ and _bookingTimes_ will be ignored. You have to be very
        careful because the variables here are sent in camelCase. Since all
        records from this method are not added live, but belatedly we give you
        the ability to receive progress information via a webhook. You will
        receive information at the address specified by you as soon as some of
        the chunks have been processed. To make it easier for you to follow what
        is happening for each record, you have the option of adding an
        additional field `importShiftAllowanceId` or `importShiftDenialId`.
        Shift examples: - Work shift: ``` { "interval": { "begin": "2023-10-02",
        "end": "2023-10-02" }, "resourceId": "64759027a6f9909999a59431",
        "workingTimes": [ { "begin": "08:00", "end": "14:40" }, { "begin":
        "15:00", "end": "18:00" } ], "bookingTimes": [ { "begin": "08:00",
        "end": "14:40" }, { "begin": "15:00", "end": "18:00" } ] } ``` -
        Vacation: ``` { "denialReason": "VACATION", "interval": { "begin":
        "2023-10-20", "end": "2023-10-22" }, "resourceId":
        "5f61c6381a34817e5c7fa220", "denialTimes": [ { "begin": "00:00", "end":
        "24:00" } ] } ``` - Sick: ``` { "denialReason": "SICK", "interval": {
        "begin": "2023-10-20", "end": "2023-10-22" }, "resourceId":
        "5f61c6381a34817e5c7fa220", "denialTimes": [ { "begin": "00:00", "end":
        "24:00" } ] } ``` - Blocker: _workingTimes_ and _bookingTimes_
        parameters are ignored ``` { "denialReason": "BLOCKER", "interval": {
        "begin": "2023-10-20", "end": "2023-10-22" }, "resourceId":
        "5f61c6381a34817e5c7fa220", "denialTimes": [ { "begin": "00:00", "end":
        "24:00" } ] } ```
      operationId: postV1TimeshiftsImportBulk
      responses:
        '201':
          description: >-
            Bulk imports time shifts and returns import result with status for
            each record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Bulk import result
                  value:
                    data:
                      created: 5
                      updated: 2
                      failed: 0
                      results:
                        - importId: shift-001
                          resourceId: 62ee11a91d66269c365407b1
                          status: SUCCESS
                          message: Work shift created successfully
                        - importId: shift-002
                          resourceId: 62ee11a91d66269c365407b1
                          status: SUCCESS
                          message: Vacation shift created successfully
                        - importId: shift-003
                          resourceId: 62ee11a91d66269c365407b2
                          status: SUCCESS
                          message: Shift updated successfully
                        - importId: shift-004
                          resourceId: 62ee11a91d66269c365407b2
                          status: SUCCESS
                          message: Sick leave created successfully
                        - importId: shift-005
                          resourceId: 62ee11a91d66269c365407b3
                          status: SUCCESS
                          message: Blocker shift created successfully
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostV1TimeshiftsImportBulkRequest'
      security:
        - BearerAuth: []
      parameters:
        - $ref: '#/components/parameters/CompanyIdHeader'
  /v1/timeshifts/{timeshiftId}:
    delete:
      tags:
        - Timeshifts
      summary: Deletes timeshift
      description: Delete a timeshift entry by its ID.
      operationId: deleteV1TimeshiftsByTimeshiftid
      responses:
        '200':
          description: >-
            Confirms deletion of the time shift and returns the deleted shift
            record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Timeshift deleted
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      resourceId: 62ee11a91d66269c365407b1
                      resourceName: John Smith
                      days:
                        - '2024-03-18'
                      workingTimes:
                        - begin: '09:00'
                          end: '17:00'
                      deletedAt: '2024-03-07T11:30:00Z'
                      ts: 1709823000
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: timeshiftId
          in: path
          required: true
          description: MongoDB ObjectId of the timeshift to operate on.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    get:
      tags:
        - Timeshifts
      summary: Fetch timeshift
      description: Retrieve a single timeshift entry by its ID.
      operationId: getV1TimeshiftsByTimeshiftid
      responses:
        '200':
          description: >-
            Returns the specified time shift with complete details including
            resource, date, and timing information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Timeshift'
              example:
                id: 65f4c840b6f1a10012ab34cd
                resourceId: 62ee11a91d66269c365407b1
                days:
                  - '2026-03-10'
                  - '2026-03-11'
                interval:
                  begin: '00:00'
                  end: '23:59'
                workingTimes:
                  - begin: '09:00'
                    end: '17:00'
                bookingTimes:
                  - begin: '09:00'
                    end: '17:00'
                denialTimes: []
                denialReason: VACATION
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: timeshiftId
          in: path
          required: true
          description: MongoDB ObjectId of the timeshift to operate on.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
    patch:
      tags:
        - Timeshifts
      summary: Updates timeshift
      description: You can find more examples in the _POST /timeshift_ Endpoint
      operationId: patchV1TimeshiftsByTimeshiftid
      responses:
        '200':
          description: Updates the time shift and returns the updated shift record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Timeshift updated
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      resourceId: 62ee11a91d66269c365407b1
                      resourceName: John Smith
                      days:
                        - '2024-03-18'
                        - '2024-03-19'
                      workingTimes:
                        - begin: '09:00'
                          end: '18:00'
                      bookingTimes:
                        - begin: '09:00'
                          end: '17:00'
                      updatedAt: '2024-03-07T11:30:00Z'
                      ts: 1709823000
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: timeshiftId
          in: path
          required: true
          description: MongoDB ObjectId of the timeshift to operate on.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchV1TimeshiftsByTimeshiftidRequest'
      security:
        - BearerAuth: []
  /v1/transactions:
    get:
      tags:
        - Transactions
      summary: List transactions
      description: List transactions for appointments.
      operationId: getV1Transactions
      responses:
        '200':
          description: >-
            Returns paginated list of appointment transactions with payment and
            gateway information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedResponse'
              examples:
                success:
                  summary: Transactions list
                  value:
                    data:
                      - id: 65f4c840b6f1a10012ab34cd
                        appointmentId: 65f5d950c7g2b20123bc45de
                        customerId: 65f6e062d8h3c31234cd56eg
                        customerName: John Doe
                        amount: 95.5
                        currency: USD
                        gateway: stripe
                        transactionRef: pi_1234567890abcdef
                        status: completed
                        paymentMethod: card
                        cardLast4: '4242'
                        createdAt: '2024-03-06T10:15:00Z'
                        updatedAt: '2024-03-06T10:15:00Z'
                        ts: 1709712900
                      - id: 65f5d951c7g2b20123bc45df
                        appointmentId: 65f7f173e9i4d42345de67fh
                        customerId: 65f8g284f0j5e53456ef78gi
                        customerName: Jane Smith
                        amount: 120
                        currency: USD
                        gateway: paypal
                        transactionRef: PP-0987654321
                        status: completed
                        paymentMethod: paypal
                        createdAt: '2024-03-05T14:30:00Z'
                        updatedAt: '2024-03-05T14:30:00Z'
                        ts: 1709650200
                    total: 2
                    meta:
                      page: 1
                      limit: 10
                      totalItems: 2
                      totalPages: 1
                    status: 1
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: paid_by_customer_id
          in: query
          required: false
          description: >-
            Filter transactions by customer ID who made payment. Must be a valid
            MongoDB ID.
          schema:
            type: string
            pattern: ^[0-9a-f]{24}$
          example: 65f4c840b6f1a10012ab34cd
        - name: gateway
          in: query
          required: false
          description: Filter transactions by payment gateway (e.g., Stripe, PayPal).
          schema:
            type: string
        - name: search
          in: query
          required: false
          description: Search transactions by text (customer name, reference).
          schema:
            type: string
          example: John
        - name: status
          in: query
          required: false
          description: Filter transactions by status (e.g., pending, completed, failed).
          schema:
            type: string
          example: active
        - name: from_date
          in: query
          required: false
          description: 'Filter transactions from start date (format: YYYY-MM-DD).'
          schema:
            type: string
            format: date
          example: '2026-03-02'
        - name: to_date
          in: query
          required: false
          description: 'Filter transactions to end date (format: YYYY-MM-DD).'
          schema:
            type: string
            format: date
          example: '2026-03-02'
        - $ref: '#/components/parameters/PageParam'
        - $ref: '#/components/parameters/LimitParam'
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
  /v1/transactions/{transactionId}:
    get:
      tags:
        - Transactions
      summary: Fetch transaction
      description: Fetch a single transaction by its ID.
      operationId: getV1TransactionsByTransactionid
      responses:
        '200':
          description: >-
            Returns the specified transaction with complete details including
            payment and gateway information.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardResponse'
              examples:
                success:
                  summary: Transaction detail
                  value:
                    data:
                      id: 65f4c840b6f1a10012ab34cd
                      appointmentId: 65f5d950c7g2b20123bc45de
                      customerId: 65f6e062d8h3c31234cd56eg
                      customerName: John Doe
                      customerEmail: john.doe@example.com
                      amount: 95.5
                      currency: USD
                      gateway: stripe
                      transactionRef: pi_1234567890abcdef
                      status: completed
                      paymentMethod: card
                      cardBrand: visa
                      cardLast4: '4242'
                      billingAddress: New York, NY 10001
                      serviceName: Hair Cut
                      resourceName: Station 1
                      appointmentDate: '2024-03-06T10:00:00Z'
                      createdAt: '2024-03-06T10:15:00Z'
                      updatedAt: '2024-03-06T10:15:00Z'
                      ts: 1709712900
                    status: 1
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
      parameters:
        - name: transactionId
          in: path
          required: true
          description: Transactionid path parameter.
          schema:
            type: string
          example: 65f4c840b6f1a10012ab34cd
        - $ref: '#/components/parameters/CompanyIdHeader'
      security:
        - BearerAuth: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT token from `/v1/auth/token` in `Authorization` header.
    BookerSecretAuth:
      type: apiKey
      in: header
      name: bs-authorization
      description: Booker-services secret token used by online booking endpoints.
  parameters:
    PageParam:
      name: page
      in: query
      required: false
      description: Page number (1-based).
      schema:
        type: integer
        minimum: 1
        default: 1
        example: 1
      example: 1
    LimitParam:
      name: limit
      in: query
      required: false
      description: |
        Maximum items per page.
        Default: 10000 (when not provided or when provided value ≤ 0).
      schema:
        type: integer
        minimum: 1
        default: 10000
        example: 50
      example: 50
    CompanyIdHeader:
      name: company-id
      in: header
      required: false
      description: Company MongoDB id used in auth context.
      schema:
        type: string
        example: 65f4c840b6f1a10012ab34cd
      example: 65f4c840b6f1a10012ab34cd
  schemas:
    PostV1AppointmentsRequest:
      type: object
      properties:
        is_bookable:
          type: boolean
          description: >-
            Whether the course appointment is available for online booking. Only
            used when is_course=true. Can be null (inherits from group service),
            true, or false.
          example: true
        has_notify_customers:
          type: boolean
          description: Has notify customers.
          example: true
        has_notify_resources:
          type: boolean
          description: Has notify resources.
          example: true
        resource_ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: >-
            Array of resource IDs (MongoDB ObjectIds). Mutually exclusive with
            external_resource_ids. At least one resource is required when
            external_resource_ids not provided.
          example:
            - 65f4c840b6f1a10012ab34cd
        external_resource_ids:
          type: array
          items:
            type: string
            example: external_resource_123
          minItems: 1
          description: >-
            Array of external resource IDs (custom external references).
            Mutually exclusive with resource_ids. Will be resolved to internal
            resource IDs.
          example:
            - external_resource_123
            - external_resource_456
        datetime:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2} \d{2}:\d{2}$
          example: 2026-03-15 14:30
          description: >-
            Appointment date and time in YYYY-MM-DD HH:mm format. Minutes must
            be divisible by 5 (e.g., :00, :05, :10, etc.)
        duration:
          type: integer
          minimum: 0
          multipleOf: 5
          description: Duration of the appointment in minutes. Must be divisible by 5.
          example: 20
        duration_before:
          type: integer
          minimum: 0
          multipleOf: 5
          description: >-
            Buffer time in minutes before the appointment. Must be divisible by
            5.
          example: 20
        duration_after:
          type: integer
          minimum: 0
          multipleOf: 5
          description: >-
            Buffer time in minutes after the appointment. Must be divisible by
            5.
          example: 20
        duration_pattern:
          type: array
          items:
            type: integer
            multipleOf: 5
            example: 15
          minItems: 1
          description: >-
            Array of durations in minutes to create appointment as. Each value
            must be divisible by 5.
          example:
            - 15
            - 20
            - 30
        service_id:
          type: string
          pattern: ^[0-9a-f]{24}$
          description: >-
            Service ID (MongoDB ObjectId). Mutually exclusive with
            external_service_id.
          example: 65f4c840b6f1a10012ab34cd
        external_service_id:
          type: string
          description: >-
            External service ID (custom external reference). Mutually exclusive
            with service_id.
          example: 65f4c840b6f1a10012ab34cd
        title:
          type: string
          description: >-
            Appointment title. Required unless all of service_id,
            external_service_id, duration, and duration_pattern are provided.
          example: example
        customer_id:
          type: string
          pattern: ^[0-9a-f]{24}$
          description: Customer ID (MongoDB ObjectId).
          example: 65f4c840b6f1a10012ab34cd
        customfields:
          type: array
          description: >-
            Custom field values for the appointment. Each item is a {id, value}
            pair.
          items:
            $ref: '#/components/schemas/CustomFieldValue'
          example:
            - id: 62ee11aa1d66269c365407c2
              value: John
        notes:
          type: string
          description: Notes.
          example: example
        reserve_for:
          type: integer
          minimum: 0
          multipleOf: 5
          description: >-
            Minutes to reserve before the appointment slot (must be divisible by
            5).
          example: 20
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        recurring:
          $ref: '#/components/schemas/RecurringPattern'
          description: >-
            Recurring appointment configuration. When provided, timezone and
            frequency are required.
        color:
          type: string
          enum:
            - '#82a774'
            - '#b22e53'
            - '#ebb65d'
            - '#95c5a6'
            - '#b26492'
            - '#cc9e52'
            - '#8ebec3'
            - '#a476ca'
            - '#e5774c'
            - '#7684ca'
            - '#5d5a79'
            - '#8b8b8b'
            - '#c46f4e'
            - '#7b6161'
            - '#6882b0'
            - '#385f87'
          description: Appointment color. Must be one of the predefined hex color codes.
          example: '#8ebec3'
        is_course:
          type: boolean
          description: >-
            If true, creates a course/group appointment. When true,
            max_participants, is_bookable, and participants become relevant.
          example: false
        max_participants:
          type: integer
          minimum: 1
          description: >-
            Maximum number of participants for a course appointment. Only used
            when is_course=true. If null/undefined, fetches default from group
            service. Must be greater than extra_persons_per_participant if
            provided.
          example: 20
        participants:
          type: array
          items:
            type: object
            properties:
              customer_id:
                type: string
                pattern: ^[0-9a-f]{24}$
                description: Participant customer ID (MongoDB ObjectId)
                example: 65f4c840b6f1a10012ab34cd
              extra_persons:
                type: integer
                minimum: 0
                description: Number of extra persons this participant brings
                example: 2
          minItems: 1
          description: Array of participant objects. Only used when is_course=true.
          example:
            - customer_id: 65f4c840b6f1a10012ab34cd
              extra_persons: 2
        tag_ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Array of tag IDs (MongoDB ObjectIds) to apply to the appointment.
          example:
            - 65f4c840b6f1a10012ab34cd
        metadata:
          type: object
          additionalProperties: true
          description: Metadata.
          example:
            key: value
        customer_reminders_minutes:
          type: integer
          minimum: 0
          description: Customer reminders minutes.
          example: 20
        resource_reminders_minutes:
          type: integer
          minimum: 0
          description: Resource reminders minutes.
          example: 20
        import_event_id:
          type: string
          description: Import event id.
          example: 65f4c840b6f1a10012ab34cd
        extra_persons_per_participant:
          type: integer
          minimum: 0
          description: >-
            Number of extra persons per participant in a course appointment.
            Only used when is_course=true.
          example: 2
        type:
          type: string
          description: Type.
          example: active
        deep_link_is_one_time_usage:
          type: string
          description: Deep link is one time usage.
          example: '09:30'
        deep_link_is_for_limited_intervals:
          type: string
          description: Deep link is for limited intervals.
          example: example
      description: >-
        Request payload for `POST /v1/appointments`. At least one of
        resource_ids or external_resource_ids is required.
      required: []
    PostV1AppointmentsDeleteBulkRequest:
      type: object
      properties:
        ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: >-
            Array of appointment IDs to delete (MongoDB ObjectIds). At least one
            ID required.
          example:
            - 65f4c840b6f1a10012ab34cd
        reason:
          type: string
          description: Reason for the deletion. Optional.
          example: example
        has_notify_customers:
          type: boolean
          description: 'Send cancellation notification to customers. Default: false'
          example: true
        has_notify_resources:
          type: boolean
          description: 'Send cancellation notification to assigned resources. Default: false'
          example: true
        skip_single_emitter:
          type: boolean
          description: >-
            Skip sending notifications to single-occurrence appointments.
            Default: false
          example: false
        skip_multiple_emitter:
          type: boolean
          description: >-
            Skip sending notifications to recurring appointment series. Default:
            false
          example: false
      description: Request payload for `POST /v1/appointments/delete/bulk`.
      required:
        - ids
    PostV1AppointmentsImportBulkRequest:
      type: object
      properties:
        events:
          type: array
          minItems: 1
          items:
            type: object
            description: >-
              Appointment object for import/update. Supports all fields from
              POST /v1/appointments plus importEventId.
            additionalProperties: true
            example:
              title: Imported Event
              datetime: 2026-03-15 14:30
              service_id: 647db96538ab9ba43dad308b
              resource_ids:
                - 64142cbefe2cfcf6373f2137
              importEventId: external-event-123
          description: >-
            Array of appointment objects to import or update. Either events or
            url must be provided. Each object supports all fields from POST
            /v1/appointments plus importEventId (string) for upsert matching
            (update existing appointment if importEventId matches, otherwise
            create new).
          example:
            - title: Imported Event
              datetime: 2026-03-15 14:30
              service_id: 647db96538ab9ba43dad308b
              resource_ids:
                - 64142cbefe2cfcf6373f2137
              importEventId: external-event-123
        url:
          type: string
          format: uri
          description: >-
            Alternative to events array - URL to retrieve appointment objects
            from. Either events or url must be provided. The response from this
            URL should contain an array of appointment objects.
          example: https://example.com/events
        secret:
          type: string
          description: >-
            Secret/token for authenticating requests to the URL. Only used when
            url is provided. Optional.
          example: Bearer token123
        has_notify_customers:
          type: boolean
          description: >-
            Send notifications to customers for imported appointments. Default:
            false
          example: true
        has_notify_resources:
          type: boolean
          description: >-
            Send notifications to assigned resources for imported appointments.
            Default: false
          example: true
        skip_emitter:
          type: boolean
          description: 'Skip sending notifications during import. Default: false'
          example: false
      description: >
        Request payload for `POST /v1/appointments/import/bulk`. Imports or
        updates multiple appointments in bulk.

        Required: Either events array OR url must be provided (mutually
        exclusive alternatives).
      required:
        - events
    PostV1AppointmentsMultipleRequest:
      type: object
      properties:
        has_notify_customers:
          type: boolean
          description: Has notify customers.
          example: true
        has_notify_resources:
          type: boolean
          description: Has notify resources.
          example: true
        is_bookable:
          type: boolean
          description: >-
            Whether the course appointment is available for online booking. Only
            used when is_course=true. Can be null (inherits from group service),
            true, or false.
          example: true
        skip_conflict_on_chained:
          type: boolean
          description: >-
            If true, allows overlapping appointment scheduling in combination
            services (chained bookings). When false, enforces no-overlap
            constraint across services.
          example: false
        datetime:
          type: string
          description: >-
            Appointment start datetime in YYYY-MM-DD HH:mm format. Minutes must
            be divisible by 5 (e.g., :00, :05, :10).
          example: 2026-03-02 09:30
          pattern: ^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}$
        title:
          type: string
          description: Title.
          example: example
        service_id:
          type: string
          pattern: ^[0-9a-f]{24}$
          description: >-
            Primary service ID (MongoDB ObjectId) for the combination
            appointment.
          example: 65f4c840b6f1a10012ab34cd
        duration:
          type: integer
          minimum: 0
          multipleOf: 5
          description: Duration of primary appointment in minutes. Must be divisible by 5.
          example: 20
        notes:
          type: string
          description: Notes.
          example: example
        duration_before:
          type: integer
          minimum: 0
          multipleOf: 5
          description: >-
            Buffer time in minutes before the appointment. Must be divisible by
            5.
          example: 20
        duration_after:
          type: integer
          minimum: 0
          multipleOf: 5
          description: >-
            Buffer time in minutes after the appointment. Must be divisible by
            5.
          example: 20
        recurring:
          $ref: '#/components/schemas/RecurringPattern'
          description: Recurring series configuration. Omit for one-off appointments.
        tag_ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Array of tag IDs (MongoDB ObjectIds) to apply to the appointment.
          example:
            - 65f4c840b6f1a10012ab34cd
        metadata:
          type: object
          additionalProperties: true
          description: Metadata.
          example:
            key: value
        customer_id:
          type: string
          pattern: ^[0-9a-f]{24}$
          description: Customer ID (MongoDB ObjectId).
          example: 65f4c840b6f1a10012ab34cd
        customfields:
          type: array
          description: >-
            Custom field values for the appointment. Each item is a {id, value}
            pair.
          items:
            $ref: '#/components/schemas/CustomFieldValue'
          example:
            - id: 62ee11aa1d66269c365407c2
              value: John
        duration_pattern:
          type: array
          items:
            type: integer
            multipleOf: 5
            example: 15
          minItems: 1
          description: >-
            Array of durations in minutes to create appointment as. Each value
            must be divisible by 5.
          example:
            - 15
            - 20
            - 30
        reserve_for:
          type: integer
          description: Reserve time in minutes. Must be divisible by 5.
          example: 15
          minimum: 0
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        color:
          type: string
          description: Appointment color. Must be one of 16 predefined hex color codes.
          example: '#82a774'
          enum:
            - '#82a774'
            - '#b22e53'
            - '#ebb65d'
            - '#95c5a6'
            - '#b26492'
            - '#cc9e52'
            - '#8ebec3'
            - '#a476ca'
            - '#e5774c'
            - '#7684ca'
            - '#5d5a79'
            - '#8b8b8b'
            - '#c46f4e'
            - '#7b6161'
            - '#6882b0'
            - '#385f87'
        is_course:
          type: boolean
          description: >-
            If true, creates a course/group appointment. When true,
            max_participants, is_bookable, and participants become relevant.
          example: false
        max_participants:
          type: integer
          minimum: 1
          description: >-
            Maximum number of participants. Required when is_course=true and
            must be ≥1.
          example: 20
        participants:
          type: array
          items:
            type: object
            properties:
              customer_id:
                type: string
                pattern: ^[0-9a-f]{24}$
                description: Participant customer ID (MongoDB ObjectId)
                example: 65f4c840b6f1a10012ab34cd
              extra_persons:
                type: integer
                minimum: 0
                description: Number of extra persons this participant brings
                example: 2
          minItems: 1
          description: Array of participant objects. Only used when is_course=true.
          example:
            - customer_id: 65f4c840b6f1a10012ab34cd
              extra_persons: 2
        customer_reminders_minutes:
          type: integer
          minimum: 0
          description: Customer reminders minutes.
          example: 20
        resource_reminders_minutes:
          type: integer
          minimum: 0
          description: Resource reminders minutes.
          example: 20
        import_event_id:
          type: string
          description: Import event id.
          example: 65f4c840b6f1a10012ab34cd
        type:
          type: string
          description: Type.
          example: active
        deep_link_is_one_time_usage:
          type: boolean
          description: Whether the pre-reservation deep link is single-use only.
          example: false
        deep_link_is_for_limited_intervals:
          type: boolean
          description: >-
            Whether the pre-reservation deep link is limited to specific time
            intervals.
          example: false
        timezone:
          type: string
          description: IANA timezone identifier (e.g., Europe/Berlin, America/New_York).
          example: Europe/Berlin
        combination_services:
          type: array
          description: >-
            List of services to combine in a single appointment. Each service
            specifies its duration and resource assignments.
          example:
            - service_id: 65f4c840b6f1a10012ab34cd
              resource_ids:
                - 65f4c840b6f1a10012ab34ce
              duration: 30
          items:
            $ref: '#/components/schemas/CombinationService'
          minItems: 1
      description: >-
        Request payload for `POST /v1/appointments/multiple`. Creates a
        multi-service appointment where the primary service_id is combined with
        additional services specified in combination_services.
      required:
        - service_id
        - duration
        - timezone
        - combination_services
        - datetime
    PostV1AppointmentsReservationRequest:
      type: object
      properties:
        service_id:
          type: string
          pattern: ^[0-9a-f]{24}$
          description: >-
            ID of the service to reserve (MongoDB ObjectId). Either service_id
            or both title and duration must be provided.
          example: 65f4c840b6f1a10012ab34cd
        title:
          type: string
          description: >-
            Appointment title. Required if service_id is not provided. Must be
            paired with duration.
          example: example
        duration:
          type: integer
          minimum: 0
          multipleOf: 5
          description: >-
            Duration in minutes. Required if service_id is not provided. Must be
            divisible by 5 (e.g., 0, 5, 10, 15, ...). Must be paired with title.
          example: 20
        resource_ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Resource IDs (MongoDB ObjectIds). Optional when reserving a slot.
          example:
            - 65f4c840b6f1a10012ab34cd
        external_resource_ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: >-
            External resource IDs. Optional when reserving a slot. Works
            alongside resource_ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        date:
          type: string
          format: date
          description: Date.
          example: '2026-03-02'
        minute:
          type: integer
          minimum: 0
          maximum: 1439
          multipleOf: 5
          description: >-
            Minute of the day (0-1439) when the appointment should be scheduled.
            Must be divisible by 5 to align with 5-minute intervals. Example:
            540 = 09:00, 1020 = 17:00.
          example: 540
      description: >
        Request payload for `POST /v1/appointments/reservation`. Reserves a time
        slot for either a pre-defined service or a custom appointment by title.

        Required fields: date and minute (always required), and either
        service_id OR both title and duration (mutually exclusive).
      required:
        - date
        - minute
    PatchV1AppointmentsByAppointmentidRequest:
      type: object
      properties:
        enforce_strict_shape:
          type: boolean
          description: Enforce strict shape for appointment scheduling.
          example: example
        is_bookable:
          type: boolean
          description: >-
            Whether the course appointment is available for online booking. Only
            used when is_course=true. Can be null (inherits from group service),
            true, or false.
          example: true
        has_notify_customers:
          type: boolean
          description: Has notify customers.
          example: true
        has_notify_resources:
          type: boolean
          description: Has notify resources.
          example: true
        participants:
          type: array
          items:
            type: object
            properties:
              customer_id:
                type: string
                pattern: ^[0-9a-f]{24}$
                description: Participant customer ID (MongoDB ObjectId)
                example: 65f4c840b6f1a10012ab34cd
              extra_persons:
                type: integer
                minimum: 0
                description: Number of extra persons this participant brings
                example: 2
          minItems: 1
          description: Array of participant objects. Only used when is_course=true.
          example:
            - customer_id: 65f4c840b6f1a10012ab34cd
              extra_persons: 2
        customer_id:
          type: string
          pattern: ^[0-9a-f]{24}$
          description: Customer ID (MongoDB ObjectId).
          example: 65f4c840b6f1a10012ab34cd
        max_participants:
          type: integer
          minimum: 1
          description: Maximum number of participants. Minimum 1 when is_course=true.
          example: 20
        duration_before:
          type: integer
          minimum: 0
          multipleOf: 5
          description: Pre-appointment buffer time in minutes. Must be divisible by 5.
          example: 20
        duration_after:
          type: integer
          minimum: 0
          multipleOf: 5
          description: Post-appointment buffer time in minutes. Must be divisible by 5.
          example: 20
        resource_ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: >-
            Resource IDs (MongoDB ObjectIds). Optional when updating
            appointment.
          example:
            - 65f4c840b6f1a10012ab34cd
        external_resource_ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: External resource IDs. Optional when updating appointment.
          example:
            - 65f4c840b6f1a10012ab34cd
        datetime:
          type: string
          description: >-
            Updated appointment start datetime in YYYY-MM-DD HH:mm format.
            Minutes must be divisible by 5.
          example: 2026-03-02 09:30
          pattern: ^\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}$
        duration:
          type: integer
          minimum: 0
          multipleOf: 5
          description: Duration in minutes. Must be divisible by 5.
          example: 20
        duration_pattern:
          type: array
          items:
            type: integer
            multipleOf: 5
            example: 15
          minItems: 1
          description: >-
            Array of durations in minutes to create appointment as. Each value
            must be divisible by 5.
          example:
            - 15
            - 20
            - 30
        service_id:
          type: string
          pattern: ^[0-9a-f]{24}$
          description: Service ID (MongoDB ObjectId).
          example: 65f4c840b6f1a10012ab34cd
        title:
          type: string
          description: Updated appointment title. Optional for PATCH operations.
          example: example
        customfields:
          type: array
          description: >-
            Custom field values for the appointment. Each item is a {id, value}
            pair.
          items:
            $ref: '#/components/schemas/CustomFieldValue'
          example:
            - id: 62ee11aa1d66269c365407c2
              value: John
        notes:
          type: string
          description: Notes.
          example: example
        reserve_for:
          type: integer
          minimum: 0
          multipleOf: 5
          description: Reserve time in minutes. Must be divisible by 5.
          example: 20
        recurring:
          $ref: '#/components/schemas/RecurringPattern'
          description: Recurring series configuration. Omit for one-off appointments.
        color:
          type: string
          description: Appointment color. Must be one of 16 predefined hex color codes.
          example: '#82a774'
          enum:
            - '#82a774'
            - '#b22e53'
            - '#ebb65d'
            - '#95c5a6'
            - '#b26492'
            - '#cc9e52'
            - '#8ebec3'
            - '#a476ca'
            - '#e5774c'
            - '#7684ca'
            - '#5d5a79'
            - '#8b8b8b'
            - '#c46f4e'
            - '#7b6161'
            - '#6882b0'
            - '#385f87'
        tag_ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Array of tag IDs (MongoDB ObjectIds) to apply to the appointment.
          example:
            - 65f4c840b6f1a10012ab34cd
        metadata:
          type: object
          additionalProperties: true
          description: Metadata.
          example:
            key: value
        extra_persons_per_participant:
          type: integer
          description: Number of extra persons per participant.
          example: example
          minimum: 0
        is_course:
          type: boolean
          description: >-
            If true, creates a course/group appointment. When true,
            max_participants, is_bookable, and participants become relevant.
          example: false
        type:
          type: string
          description: Type.
          example: active
        deep_link_is_one_time_usage:
          type: boolean
          description: Whether the pre-reservation deep link is single-use only.
          example: '09:30'
        deep_link_is_for_limited_intervals:
          type: boolean
          description: >-
            Whether the pre-reservation deep link is limited to specific time
            intervals.
          example: example
        customer_reminders_minutes:
          type: integer
          minimum: 0
          description: Customer reminders minutes.
          example: 20
        resource_reminders_minutes:
          type: integer
          minimum: 0
          description: Resource reminders minutes.
          example: 20
        import_event_id:
          type: string
          description: Import event id.
          example: 65f4c840b6f1a10012ab34cd
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
      description: >-
        Request payload for `PATCH /v1/appointments/{appointmentId}`. Only
        fields provided in the request body will be updated.
      required: []
    Appointment:
      type: object
      description: A TIMIFY appointment (booking event).
      properties:
        id:
          type: string
          description: TIMIFY internal MongoDB ID.
          example: 65f4c840b6f1a10012ab34cd
        title:
          type: string
          description: Appointment title / name.
          example: Consultation
        resourceId:
          type: string
          description: Primary resource (calendar) ID.
          example: 62ee11a91d66269c365407b1
        color:
          type: string
          description: Hex color code used in the calendar.
          example: '#8ebec3'
        companyName:
          type: string
          description: Name of the company owning this appointment.
        customers:
          type: array
          description: Customers attached to this appointment.
          items:
            $ref: '#/components/schemas/Customer'
        serviceId:
          type: string
          description: ID of the booked service.
          example: 647db96538ab9ba43dad308b
        datetime:
          type: string
          description: Appointment start datetime.
          example: 2026-03-06 10:00
        duration:
          type: integer
          description: Duration in minutes.
          example: 60
        durationBefore:
          type: integer
          description: Buffer time before appointment in minutes.
          example: 0
        durationAfter:
          type: integer
          description: Buffer time after appointment in minutes.
          example: 0
        notes:
          type: string
          description: Internal notes.
          example: Confirmed via API
        externalId:
          type: string
          description: Your system's external identifier.
          nullable: true
        isBookable:
          type: boolean
          description: Whether the appointment can be booked online.
          example: true
        isCourse:
          type: boolean
          description: Whether this is a group service (course/event) appointment.
          example: false
        maxParticipants:
          type: integer
          description: Maximum number of participants (for group services).
          nullable: true
        tagIds:
          type: array
          description: IDs of tags applied to this appointment.
          items:
            type: string
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 date-time when the appointment was created.
          example: '2026-03-06T10:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 date-time when the appointment was last updated.
          example: '2026-03-06T10:05:00.000Z'
        type:
          type: string
          description: Appointment type identifier.
          example: BOOKING
        price:
          type: number
          nullable: true
          description: Price of the appointment.
          example: 99.99
        date:
          type: string
          description: Appointment date (YYYY-MM-DD or ISO).
          example: '2026-03-06'
        startDate:
          type: string
          description: Appointment start date-time string.
          example: '2026-03-06T10:00:00.000Z'
        createdBy:
          type: string
          nullable: true
          description: Display name of the creator.
        createdByUserId:
          type: string
          nullable: true
          description: User ID of the creator.
        createdByScope:
          type: string
          nullable: true
          description: Auth scope used when created (e.g. user, app).
        updatedBy:
          type: string
          nullable: true
          description: Display name of the last updater.
        updatedByUserId:
          type: string
          nullable: true
          description: User ID of the last updater.
        updatedByScope:
          type: string
          nullable: true
          description: Auth scope used when last updated.
        timestamp:
          type: integer
          nullable: true
          description: Unix timestamp of appointment start.
        isOnlineBooking:
          type: boolean
          description: Whether the appointment was created via online booking.
          example: false
        isPaidOnlineWithStripe:
          type: boolean
          description: Whether the appointment was paid online via Stripe.
          example: false
        isPaidOnlineWithPaypal:
          type: boolean
          description: Whether the appointment was paid online via PayPal.
          example: false
        hasNotifyCustomers:
          type: boolean
          description: Whether customers were notified.
          example: false
        hasNotifyResources:
          type: boolean
          description: Whether resources were notified.
          example: false
        participants:
          type: integer
          nullable: true
          description: Number of participants in this appointment.
        resources:
          type: array
          nullable: true
          description: Resources (calendars) assigned to this appointment.
          items:
            type: object
        tags:
          type: array
          nullable: true
          description: Tags applied to this appointment.
          items:
            type: object
        chainId:
          type: string
          nullable: true
          description: Chain ID for linked/recurring appointments.
        chainedEvents:
          type: array
          nullable: true
          description: IDs of other appointments in the chain.
          items:
            type: string
        location:
          type: object
          nullable: true
          description: Location details for this appointment.
        customfields:
          type: array
          nullable: true
          description: Custom field values on this appointment.
          items:
            type: object
        singleCustomers:
          type: array
          nullable: true
          description: Individual customers (non-grouped) on this appointment.
          items:
            type: object
        service:
          type: object
          nullable: true
          description: Embedded service details.
        recurring:
          type: object
          nullable: true
          description: Recurring rule/pattern if this is a recurring appointment.
        combination:
          type: object
          nullable: true
          description: Combination service details if multi-service appointment.
        metadata:
          type: object
          nullable: true
          description: Arbitrary metadata map.
        scheduledForDeletionAt:
          type: string
          nullable: true
          description: ISO date-time when this appointment is scheduled for deletion.
    AuthTokenResponse:
      type: object
      required:
        - accessToken
        - refreshToken
        - expires
      properties:
        accessToken:
          type: string
          description: Access token used as bearer token.
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
        refreshToken:
          type: string
          description: Refresh token used to obtain a new access token.
          example: d8f8f4ec-6fb4-4e39-b5db-74041a3f8dc1
        expires:
          type: integer
          description: Token validity in seconds.
          example: 7200
    PostV1AuthRefreshtokenRequest:
      type: object
      properties:
        refreshtoken:
          type: string
          description: >-
            Refresh token obtained from POST /v1/auth/token endpoint. Takes
            precedence over query parameter.
          example: >-
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZWZyZXNoIjp0cnVlfQ.8X_9UiY4Rq65xB1PrigTyEuHLCGOVJnxn_4cMx9hSuY
      description: >-
        Request payload for `POST /v1/auth/refreshtoken`. Refresh token can
        alternatively be provided as query parameter.
    PostV1AuthTokenRequest:
      type: object
      properties:
        appid:
          type: string
          description: Your application ID, provided when you register a Dev API app.
          example: 65f4c840b6f1a10012ab34cd
        appsecret:
          type: string
          description: Your application secret, provided when you register a Dev API app.
          example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
      description: Request payload for `POST /v1/auth/token`.
      required:
        - appid
        - appsecret
    AvailabilityResponse:
      type: object
      description: >-
        Availability data for a service, including available days and resource
        info.
      properties:
        calendarBegin:
          type: string
          description: Start of the allowed booking window.
          example: 2026-03-05 11:40
        calendarEnd:
          type: string
          description: End of the allowed booking window.
          example: 2027-03-05 11:40
        serviceId:
          type: string
          description: ID of the queried service.
          example: 647db96538ab9ba43dad308b
        serviceName:
          type: string
          description: Name of the queried service.
          example: Hair Cut
        duration:
          type: integer
          description: Default service duration in minutes.
          example: 60
        selectedResourceIds:
          type: array
          description: Resource IDs pre-selected by the caller.
          items:
            type: string
        resourceCategories:
          type: array
          description: Resource categories that serve this service.
          items:
            type: object
            properties:
              id:
                type: string
                example: 62ee11a91d66269c365407b0
              name:
                type: string
                example: Main Resources
              orderIndex:
                type: integer
                example: 1
        resources:
          type: array
          description: Individual resources available for this service.
          items:
            $ref: '#/components/schemas/AvailabilityResource'
        dependencies:
          type: array
          description: Resource dependency groups (multi-resource service segments).
          items:
            type: object
            properties:
              name:
                type: string
                nullable: true
              resourceIds:
                type: array
                items:
                  type: string
        onDays:
          type: array
          description: Dates that have at least one available time slot.
          items:
            type: string
            format: date
          example:
            - '2026-03-05'
            - '2026-03-06'
            - '2026-03-09'
        offDays:
          type: array
          description: Dates that are fully booked with no available slots.
          items:
            type: string
            format: date
        slots:
          type: object
          description: >-
            Available time slots per requested day. Only present when the
            `days[]` parameter is used.
          additionalProperties:
            type: array
            items:
              type: string
              example: '09:00'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message.
          example: Invalid request payload
        name:
          type: string
          description: Error class name.
          example: BadRequestError
        errorCode:
          type: string
          description: Application-specific error code.
          example: 2
        details:
          type: object
          description: Structured error details.
          additionalProperties: true
          example:
            query:
              page: invalid
        extras:
          type: object
          description: Extra error metadata from downstream services.
          nullable: true
          additionalProperties: true
          example:
            code: GRAPHQL_VALIDATION_FAILED
    ApiMeta:
      type: object
      required:
        - page
        - limit
        - totalItems
        - totalPages
      properties:
        page:
          type: integer
          description: Current page number.
          example: 1
        limit:
          type: integer
          description: Items requested per page.
          example: 20
        totalItems:
          type: integer
          description: Total items available.
          example: 182
        totalPages:
          type: integer
          description: Total pages available.
          example: 10
    GenericRecord:
      type: object
      description: Generic response data object for proxied GraphQL entities.
      additionalProperties: true
      example:
        id: 65f4c840b6f1a10012ab34cd
        externalId: ext_1001
        name: Demo value
    StandardResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/GenericRecord'
        status:
          type: integer
          description: Operation status flag.
          example: 1
      example:
        data:
          id: 65f4c840b6f1a10012ab34cd
          externalId: ext_1001
          firstName: John
          lastName: Doe
          fullName: John Doe
          email: john@example.com
          phone:
            phone: '+1234567890'
            number: '1234567890'
            code: US
          tags:
            - tag1
            - tag2
          totalBookings: 5
          avatarUrl: https://example.com/avatar.jpg
          firstLetters: JD
          createdAt: '2024-01-15T10:30:00Z'
          updatedAt: '2024-02-20T14:45:30Z'
          ts: 1708430730
        status: 1
    PaginatedResponse:
      type: object
      required:
        - data
      properties:
        data:
          type: array
          description: List payload.
          example:
            - id: 65f4c840b6f1a10012ab34cd
              externalId: ext_1001
              firstName: John
              lastName: Doe
              fullName: John Doe
              email: john@example.com
              totalBookings: 5
              createdAt: '2024-01-15T10:30:00Z'
              updatedAt: '2024-02-20T14:45:30Z'
              ts: 1708430730
            - id: 65f4c840b6f1a10012ab34ce
              externalId: ext_1002
              firstName: Jane
              lastName: Smith
              fullName: Jane Smith
              email: jane@example.com
              totalBookings: 3
              createdAt: '2024-01-20T11:15:00Z'
              updatedAt: '2024-02-25T13:22:00Z'
              ts: 1708516200
          items:
            $ref: '#/components/schemas/GenericRecord'
        meta:
          $ref: '#/components/schemas/ApiMeta'
        total:
          type: integer
          description: Total count used by legacy list endpoints.
          example: 182
        status:
          type: integer
          description: Operation status flag.
          example: 1
      example:
        total: 182
        data:
          - id: 65f4c840b6f1a10012ab34cd
            externalId: ext_1001
            firstName: John
            lastName: Doe
            fullName: John Doe
            email: john@example.com
            totalBookings: 5
            createdAt: '2024-01-15T10:30:00Z'
            updatedAt: '2024-02-20T14:45:30Z'
            ts: 1708430730
          - id: 65f4c840b6f1a10012ab34ce
            externalId: ext_1002
            firstName: Jane
            lastName: Smith
            fullName: Jane Smith
            email: jane@example.com
            totalBookings: 3
            createdAt: '2024-01-20T11:15:00Z'
            updatedAt: '2024-02-25T13:22:00Z'
            ts: 1708516200
        status: 1
    WhoAmIResponse:
      type: object
      required:
        - what
        - region
        - env
        - version
      properties:
        what:
          type: string
          description: Service identifier.
          example: dev-api
        region:
          type: string
          description: Deployment region.
          example: eu-central-1
        env:
          type: string
          description: Runtime environment.
          example: production
        version:
          type: string
          description: Service version.
          example: 0.0.4
    PhoneObject:
      type: object
      description: Structured international phone number.
      properties:
        phone:
          type: string
          description: Full phone number with country prefix.
          example: '+4477777777'
        number:
          type: string
          description: Local number without country prefix.
          example: '77777777'
        code:
          type: string
          description: ISO 3166-1 alpha-2 country code.
          example: GB
    RecurringPattern:
      type: object
      description: >-
        Recurring appointment configuration. Use to create a series of repeating
        appointments. When provided, both 'frequency' and 'timezone' fields are
        REQUIRED.
      properties:
        frequency:
          type: string
          description: >-
            Recurrence frequency. REQUIRED when recurring configuration is
            provided.
          enum:
            - DAYS
            - WEEKS
            - MONTHS
            - YEARS
          example: WEEKS
        timezone:
          type: string
          description: >-
            IANA timezone for the recurrence calculation (e.g., "Europe/Berlin",
            "America/New_York", "UTC"). REQUIRED when recurring configuration is
            provided.
          example: Europe/Berlin
        repeat_last_date:
          type: string
          format: date
          description: Stop repeating on or before this date (YYYY-MM-DD format).
          example: '2026-12-31'
        repeat_times:
          type: integer
          description: Number of times to repeat (alternative to repeat_last_date).
          example: 10
        week_days:
          type: array
          description: >-
            Days of week to repeat on (0=Sunday … 6=Saturday). Used when
            frequency=WEEKS.
          items:
            type: integer
            minimum: 0
            maximum: 6
          example:
            - 1
            - 3
            - 5
        month_days:
          type: array
          description: Days of month to repeat on. Used when frequency=MONTHS.
          items:
            type: integer
            minimum: 1
            maximum: 31
        year_months:
          type: array
          description: Months to repeat on (1=Jan … 12=Dec). Used when frequency=YEARS.
          items:
            type: integer
            minimum: 1
            maximum: 12
    PutV1CompaniesByIdSettingsRequest:
      type: object
      properties:
        footfall_mapping:
          type: string
          description: Footfall mapping.
          example: example
        services_allocation:
          type: string
          description: Services allocation.
          example: example
        snap_to_grid_interval:
          type: string
          description: Snap to grid interval.
          example: example
        internal_snap_to_grid_interval:
          type: string
          description: Internal snap to grid interval.
          example: example
        has_facebook_login:
          type: boolean
          description: Has facebook login.
          example: true
        has_timify_login:
          type: boolean
          description: Has timify login.
          example: true
        has_guest_booking:
          type: boolean
          description: Has guest booking.
          example: true
        show_widget_timezone_selector:
          type: string
          description: Show widget timezone selector.
          example: '09:30'
        hide_fast_widget_time_frame:
          type: string
          description: Hide fast widget time frame.
          example: '09:30'
        maximum_lead_time_months:
          type: string
          description: Maximum lead time months.
          example: '09:30'
        minimum_lead_time_hours:
          type: string
          description: Minimum lead time hours.
          example: '09:30'
        maximum_lead_time:
          type: string
          description: Maximum lead time.
          example: '09:30'
        minimum_lead_time:
          type: string
          description: Minimum lead time.
          example: '09:30'
        online_reservation_minutes:
          type: integer
          minimum: 0
          description: Online reservation minutes.
          example: 20
        cancellation_lead_time_hours:
          type: string
          description: Cancellation lead time hours.
          example: '09:30'
        cancellation_lead_time:
          type: string
          description: Cancellation lead time.
          example: '09:30'
        reset_copy_booking_clipboard_after_paste:
          type: string
          description: Reset copy booking clipboard after paste.
          example: example
        customer_email_reminders_minutes:
          type: integer
          minimum: 0
          description: Customer email reminders minutes.
          example: 20
        resource_email_reminders_minutes:
          type: integer
          minimum: 0
          description: Resource email reminders minutes.
          example: 20
        resource_reminders_email_recipients:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Resource reminders email recipients.
          example:
            - 65f4c840b6f1a10012ab34cd
        customer_reminders_email_recipients:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Customer reminders email recipients.
          example:
            - 65f4c840b6f1a10012ab34cd
        resource_booking_create_email_recipients:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Resource booking create email recipients.
          example:
            - 65f4c840b6f1a10012ab34cd
        resource_booking_update_email_recipients:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Resource booking update email recipients.
          example:
            - 65f4c840b6f1a10012ab34cd
        resource_booking_delete_email_recipients:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Resource booking delete email recipients.
          example:
            - 65f4c840b6f1a10012ab34cd
        customer_booking_create_email_recipients:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Customer booking create email recipients.
          example:
            - 65f4c840b6f1a10012ab34cd
        customer_booking_update_email_recipients:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Customer booking update email recipients.
          example:
            - 65f4c840b6f1a10012ab34cd
        customer_booking_delete_email_recipients:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Customer booking delete email recipients.
          example:
            - 65f4c840b6f1a10012ab34cd
        online_booking_filling_type:
          type: string
          description: Online booking filling type.
          example: example
        apply_slot_optimisation:
          type: string
          description: Apply slot optimisation.
          example: example
        show_widget_language_selector:
          type: string
          description: Show widget language selector.
          example: example
        is_widget_weekly_view:
          type: boolean
          description: Is widget weekly view.
          example: true
        show_widget_categories_closed:
          type: string
          description: Show widget categories closed.
          example: example
        show_widget_first_category_open:
          type: string
          description: Show widget first category open.
          example: example
        widget_external_url_redirect:
          type: string
          format: uri
          description: Widget external url redirect.
          example: https://example.com
        custom_terms_and_conditions_url:
          type: string
          format: uri
          description: Custom terms and conditions url.
          example: https://example.com
        custom_privacy_policy_url:
          type: string
          format: uri
          description: Custom privacy policy url.
          example: https://example.com
        custom_offline_booking_message:
          type: string
          description: Custom offline booking message.
          example: example
        enforce_resources_allowance_type:
          type: string
          description: Enforce resources allowance type.
          example: example
        hide_service_duration:
          type: integer
          minimum: 0
          description: Hide service duration.
          example: 20
        hide_resources_section:
          type: string
          description: Hide resources section.
          example: example
        show_external_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Show external ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        has_notify_customer_selected:
          type: boolean
          description: Has notify customer selected.
          example: true
        has_notify_resource_selected:
          type: boolean
          description: Has notify resource selected.
          example: true
        has_notify_on_customers:
          type: boolean
          description: Has notify on customers.
          example: true
        has_notify_on_resources:
          type: boolean
          description: Has notify on resources.
          example: true
        forbid_creating_and_updating_bookings_in_the_past:
          type: string
          description: Forbid creating and updating bookings in the past.
          example: example
        forbid_more_than_one_booking_in_FBW:
          type: string
          description: Forbid more than one booking in fbw.
          example: example
        show_add_service_combinations:
          type: string
          description: Show add service combinations.
          example: example
        enforce_service_duration_limit:
          type: integer
          minimum: 0
          description: Enforce service duration limit.
          example: 20
        enforce_rescheduling_tag_rule:
          type: string
          description: Enforce rescheduling tag rule.
          example: example
        EUGDPR_rules:
          type: string
          description: Eugdpr rules.
          example: example
        allow_user_locale_for_resources:
          type: string
          description: Allow user locale for resources.
          example: example
        allow_user_locale_for_customers:
          type: string
          description: Allow user locale for customers.
          example: example
        public_holidays:
          type: string
          description: Public holidays.
          example: example
        required_auth_2FA_type:
          type: string
          description: Required auth 2fa type.
          example: example
        widget_conversions:
          type: object
          additionalProperties: true
          description: Widget conversions.
          example:
            key: value
        security_session_config:
          type: object
          additionalProperties: true
          description: Security session config.
          example:
            key: value
        security_session_inactivity_config:
          type: object
          additionalProperties: true
          description: Security session inactivity config.
          example:
            key: value
        disclaimer_config:
          type: object
          additionalProperties: true
          description: Disclaimer config.
          example:
            key: value
        date_format:
          type: string
          format: date
          description: Date format.
          example: '2026-03-02'
        time_format:
          type: string
          description: Time format.
          example: '09:30'
        availability_display_config:
          type: object
          additionalProperties: true
          description: Availability display config.
          example:
            key: value
      description: Request payload for `PUT /v1/companies/{id}/settings`.
    PostV1IcsCompaniesSubscriptionRequest:
      type: object
      properties:
        id:
          type: string
          description: Id.
          example: 65f4c840b6f1a10012ab34cd
        icsConfigStatus:
          type: string
          description: Icsconfigstatus.
          example: example
      description: Request payload for `POST /v1/ics/companies/subscription`.
    PostV1CustomersRequest:
      type: object
      properties:
        customfields:
          type: array
          description: >-
            Custom field values for the customer. Each item contains an id and
            value. The id must be a valid MongoDB ObjectId of a custom field
            definition.
          items:
            $ref: '#/components/schemas/CustomFieldValue'
          example:
            - id: 62ee11aa1d66269c365407c2
              value: John
        external_id:
          type: string
          description: >-
            External identifier for the customer. Used for syncing with external
            systems. Optional unique value per company.
          example: EXT-CUST-12345
        ignore_mandatory_validation:
          type: boolean
          description: >-
            Skip mandatory field validation during customer creation. Set to
            true to allow creating customers without all required custom fields.
            Default false.
          example: false
        import_customer_id:
          type: string
          description: >-
            Customer ID from previous system when importing/migrating data. Used
            to map external customer records.
          example: legacy-customer-789
      description: Request payload for `POST /v1/customers`.
    PostV1CustomersCustomfieldsRequest:
      type: object
      properties:
        is_mandatory_online:
          type: boolean
          description: Make this custom field mandatory for online bookings. Default false.
          example: true
        is_mandatory_offline:
          type: boolean
          description: >-
            Make this custom field mandatory for offline bookings. Default
            false.
          example: true
        external_id:
          type: string
          description: >-
            External identifier for the custom field. Used for syncing with
            external systems.
          example: EXT-FIELD-12345
        label:
          type: string
          description: >-
            Display label for the custom field shown to customers and staff.
            Identifies the field purpose.
          example: Customer Preferences
        type:
          type: string
          description: >-
            Data type of the custom field. Determines input validation and
            display format.
          example: TEXT
          enum:
            - TEXT
            - CHECKBOX
            - SELECT
            - MULTIPLE
            - DATE
            - TEXTAREA
            - EMAIL
            - ADDRESS
            - PHONE
            - FILE
            - TIMEZONE
        options:
          type: string
          description: >-
            Options for SELECT/MULTIPLE fields. JSON array of option strings.
            For other field types, can be empty. Example for SELECT: ["Option
            A", "Option B", "Option C"]
          example: '["Option A", "Option B"]'
        active:
          type: boolean
          description: >-
            Enable or disable this custom field. Disabled fields are hidden from
            new bookings.
          example: true
        published:
          type: boolean
          description: >-
            Publish this custom field. Published fields are visible to
            customers.
          example: true
        is_after_auth:
          type: boolean
          description: >-
            Show this field only after customer authentication/login. Default
            false.
          example: true
        is_unique_key:
          type: boolean
          description: >-
            Enforce unique values for this field across all customers. Default
            false.
          example: true
        description:
          type: string
          description: >-
            Help text or additional instructions shown to customers filling out
            this field.
          example: Please describe your booking preferences in detail
        specific_service_category_ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: >-
            Limit this custom field to specific service categories. Array of
            MongoDB ObjectIds.
          example:
            - 65f4c840b6f1a10012ab34cd
        specific_course_category_ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: >-
            Limit this custom field to specific course categories. Array of
            MongoDB ObjectIds.
          example:
            - 65f4c840b6f1a10012ab34cd
        service_ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: >-
            Services that require/use this custom field. Array of valid MongoDB
            ObjectIds.
          example:
            - 65f4c840b6f1a10012ab34cd
        course_ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: >-
            Courses that require/use this custom field. Array of valid MongoDB
            ObjectIds.
          example:
            - 65f4c840b6f1a10012ab34cd
        category_id:
          type: string
          pattern: ^[0-9a-f]{24}$
          description: >-
            Category that groups this custom field with related fields. Must be
            valid MongoDB ObjectId.
          example: 65f4c840b6f1a10012ab34cd
        has_overwrite:
          type: boolean
          description: >-
            Allow overwriting existing field values when updating customers.
            Default true.
          example: true
        price:
          type: number
          minimum: 0
          description: >-
            Optional cost to charge customers for providing this information.
            Leave empty if no charge.
          example: 19.9
        duration:
          type: integer
          minimum: 0
          multipleOf: 5
          description: >-
            Duration in minutes required to process answers to this field. Must
            be divisible by 5.
          example: 20
        order_index:
          type: integer
          description: >-
            Display order position among custom fields. Lower numbers appear
            first.
          example: 1
        field_type:
          type: string
          description: >-
            Internal field type classification. Used for categorizing custom
            fields.
          example: TEXT
      description: Request payload for `POST /v1/customers/customfields`.
      required:
        - label
        - type
        - service_ids
        - course_ids
        - category_id
    PostV1CustomersCustomfieldsCategoriesRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
      description: Request payload for `POST /v1/customers/customfields/categories`.
      required:
        - name
    PatchV1CustomersCustomfieldsCategoriesByCategoryidRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
      description: >-
        Request payload for `PATCH
        /v1/customers/customfields/categories/{categoryId}`.
      required:
        - name
    PatchV1CustomersCustomfieldsByFieldidRequest:
      type: object
      properties:
        is_mandatory_online:
          type: boolean
          description: Is mandatory online.
          example: true
        is_mandatory_offline:
          type: boolean
          description: Is mandatory offline.
          example: true
        label:
          type: string
          description: Label.
          example: example
        type:
          type: string
          description: Type.
          example: active
        options:
          type: string
          description: Options.
          example: example
        active:
          type: string
          description: Active.
          example: example
        published:
          type: string
          description: Published.
          example: example
        is_unique_key:
          type: boolean
          description: Is unique key.
          example: true
        is_after_auth:
          type: boolean
          description: Is after auth.
          example: true
        description:
          type: string
          description: Description.
          example: example
        specific_service_category_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Specific service category ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        specific_course_category_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Specific course category ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        service_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Service ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        course_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Course ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        category_id:
          type: string
          description: Category id.
          example: 65f4c840b6f1a10012ab34cd
        has_overwrite:
          type: boolean
          description: Has overwrite.
          example: true
        price:
          type: number
          minimum: 0
          description: Price.
          example: 19.9
        duration:
          type: integer
          minimum: 0
          description: Duration.
          example: 20
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        order_index:
          type: string
          description: Order index.
          example: example
      description: Request payload for `PATCH /v1/customers/customfields/{fieldId}`.
      required:
        - label
        - type
        - options
        - service_ids
        - course_ids
        - category_id
    PostV1CustomersImportRequest:
      type: object
      properties:
        customers:
          type: string
          description: Customers.
          example: example
        url:
          type: string
          format: uri
          description: Url.
          example: https://example.com
        secret:
          type: string
          description: Secret.
          example: example
        skip_emitter:
          type: string
          description: Skip emitter.
          example: example
      description: Request payload for `POST /v1/customers/import`.
    PatchV1CustomersByCustomeridRequest:
      type: object
      properties:
        customfields:
          type: array
          description: >-
            Custom field values for the appointment. Each item is a {id, value}
            pair.
          items:
            $ref: '#/components/schemas/CustomFieldValue'
          example:
            - id: 62ee11aa1d66269c365407c2
              value: John
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        ignore_mandatory_validation:
          type: string
          description: Ignore mandatory validation.
          example: example
        import_customer_id:
          type: string
          description: Import customer id.
          example: 65f4c840b6f1a10012ab34cd
      description: Request payload for `PATCH /v1/customers/{customerId}`.
    PostV1EnterpriseCustomersRequest:
      type: object
      properties:
        customfields:
          type: array
          description: >-
            Custom field values for the appointment. Each item is a {id, value}
            pair.
          items:
            $ref: '#/components/schemas/CustomFieldValue'
          example:
            - id: 62ee11aa1d66269c365407c2
              value: John
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        ignore_mandatory_validation:
          type: string
          description: Ignore mandatory validation.
          example: example
        import_customer_id:
          type: string
          description: Import customer id.
          example: 65f4c840b6f1a10012ab34cd
      description: Request payload for `POST /v1/enterprise-customers`.
    PostV1EnterpriseCustomersCustomfieldsRequest:
      type: object
      properties:
        is_mandatory_online:
          type: boolean
          description: Is mandatory online.
          example: true
        is_mandatory_offline:
          type: boolean
          description: Is mandatory offline.
          example: true
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        label:
          type: string
          description: Label.
          example: example
        type:
          type: string
          description: Type.
          example: active
        options:
          type: string
          description: Options.
          example: example
        active:
          type: string
          description: Active.
          example: example
        published:
          type: string
          description: Published.
          example: example
        is_unique_key:
          type: boolean
          description: Is unique key.
          example: true
        description:
          type: string
          description: Description.
          example: example
        specific_service_category_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Specific service category ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        specific_course_category_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Specific course category ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        service_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Service ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        course_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Course ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        category_id:
          type: string
          description: Category id.
          example: 65f4c840b6f1a10012ab34cd
        has_overwrite:
          type: boolean
          description: Has overwrite.
          example: true
        price:
          type: number
          minimum: 0
          description: Price.
          example: 19.9
        duration:
          type: integer
          minimum: 0
          description: Duration.
          example: 20
        order_index:
          type: string
          description: Order index.
          example: example
      description: Request payload for `POST /v1/enterprise-customers/customfields`.
      required:
        - label
        - type
        - options
        - service_ids
        - course_ids
        - category_id
    PostV1EnterpriseCustomersCustomfieldsCategoriesRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
      description: >-
        Request payload for `POST
        /v1/enterprise-customers/customfields/categories`.
      required:
        - name
    PatchV1EnterpriseCustomersCustomfieldsCategoriesByCategoryidRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
      description: >-
        Request payload for `PATCH
        /v1/enterprise-customers/customfields/categories/{categoryId}`.
    PatchV1EnterpriseCustomersCustomfieldsByFieldidRequest:
      type: object
      properties:
        is_mandatory_online:
          type: boolean
          description: Is mandatory online.
          example: true
        is_mandatory_offline:
          type: boolean
          description: Is mandatory offline.
          example: true
        label:
          type: string
          description: Label.
          example: example
        type:
          type: string
          description: Type.
          example: active
        options:
          type: string
          description: Options.
          example: example
        active:
          type: string
          description: Active.
          example: example
        published:
          type: string
          description: Published.
          example: example
        is_unique_key:
          type: boolean
          description: Is unique key.
          example: true
        description:
          type: string
          description: Description.
          example: example
        specific_service_category_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Specific service category ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        specific_course_category_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Specific course category ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        service_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Service ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        course_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Course ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        category_id:
          type: string
          description: Category id.
          example: 65f4c840b6f1a10012ab34cd
        has_overwrite:
          type: boolean
          description: Has overwrite.
          example: true
        price:
          type: number
          minimum: 0
          description: Price.
          example: 19.9
        duration:
          type: integer
          minimum: 0
          description: Duration.
          example: 20
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        order_index:
          type: string
          description: Order index.
          example: example
      description: >-
        Request payload for `PATCH
        /v1/enterprise-customers/customfields/{fieldId}`.
      required:
        - label
        - type
        - options
        - service_ids
        - course_ids
        - category_id
    PostV1EnterpriseCustomersImportRequest:
      type: object
      properties:
        customers:
          type: string
          description: Customers.
          example: example
        url:
          type: string
          format: uri
          description: Url.
          example: https://example.com
        secret:
          type: string
          description: Secret.
          example: example
        chunk_size:
          type: string
          description: Chunk size.
          example: example
        affected_branch_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        affected_branch_external_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch external ids.
          example:
            - 65f4c840b6f1a10012ab34cd
      description: Request payload for `POST /v1/enterprise-customers/import`.
    PatchV1EnterpriseCustomersByCustomeridRequest:
      type: object
      properties:
        customfields:
          type: array
          description: >-
            Custom field values for the appointment. Each item is a {id, value}
            pair.
          items:
            $ref: '#/components/schemas/CustomFieldValue'
          example:
            - id: 62ee11aa1d66269c365407c2
              value: John
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        ignore_mandatory_validation:
          type: string
          description: Ignore mandatory validation.
          example: example
        import_customer_id:
          type: string
          description: Import customer id.
          example: 65f4c840b6f1a10012ab34cd
      description: Request payload for `PATCH /v1/enterprise-customers/{customerId}`.
    CustomerField:
      type: object
      description: A custom field value attached to a customer record.
      properties:
        id:
          type: string
          description: Custom field instance ID.
          example: 62ee11aa1d66269c365407be
        type:
          type: string
          description: Field data type.
          enum:
            - TEXT
            - EMAIL
            - PHONE
            - SELECT
            - TEXTAREA
            - ADDRESS
          example: TEXT
        value:
          type: string
          description: >-
            Field value (Phone fields use JSON string:
            {"number":"123","country":"DE"}).
          example: John
        values:
          type: array
          description: Multi-value array (for multi-select fields).
          items:
            type: string
        isMultiple:
          type: boolean
          nullable: true
          description: Whether the field supports multiple values.
        defaultId:
          type: string
          description: Default field identifier (e.g., firstName, email, notes).
          example: firstName
        label:
          type: string
          description: Human-readable field label.
          example: First Name
    Customer:
      type: object
      description: A TIMIFY customer (booker / end-user).
      properties:
        id:
          type: string
          description: TIMIFY internal MongoDB ID.
          example: 6661c401acdc63cf1f63be8d
        externalId:
          type: string
          description: Your system's external identifier.
          example: KS
        globalId:
          type: string
          description: Enterprise-level global customer ID.
          example: 637cbec9bb6be45322482249
        firstName:
          type: string
          description: Customer's first name.
          example: John
        lastName:
          type: string
          description: Customer's last name.
          example: Smith
        fullName:
          type: string
          description: Full display name (first + last name concatenated).
          example: John Smith
        companyName:
          type: string
          description: Customer's company or organisation name.
          example: ''
        email:
          type: string
          format: email
          description: Customer's primary email address.
          example: john.smith@example.com
        phone:
          $ref: '#/components/schemas/PhoneObject'
        tags:
          type: array
          description: Tags assigned to this customer.
          items:
            $ref: '#/components/schemas/TagReference'
        totalBookings:
          type: integer
          description: Total number of appointments this customer has booked.
          example: 5
        avatarUrl:
          type: string
          nullable: true
          description: URL to the customer's avatar image.
          example: ''
        firstLetters:
          type: array
          description: Array of initial letters used for avatar placeholder.
          items:
            type: string
          example:
            - J
            - S
        fields:
          type: array
          description: Custom field values for this customer.
          items:
            $ref: '#/components/schemas/CustomerField'
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 date-time when the customer record was created.
          example: '2023-06-06T10:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 date-time when the customer record was last updated.
          example: '2024-12-01T09:15:00.000Z'
        resourceIds:
          type: array
          description: IDs of resources this customer is linked to.
          items:
            type: string
        resourceCategoryIds:
          type: array
          description: IDs of resource categories this customer is linked to.
          items:
            type: string
        internalId:
          type: string
          description: Internal/global reference ID.
          example: 637cbec9bb6be45322482249
        tagIds:
          type: array
          description: IDs of tags applied to this customer.
          items:
            type: string
        ts:
          type: integer
          nullable: true
          description: Unix timestamp of last update.
    CustomFieldValue:
      type: object
      description: A custom field id/value pair for appointment or customer fields.
      required:
        - id
        - value
      properties:
        id:
          type: string
          description: Custom field definition ID.
          example: 62ee11aa1d66269c365407c2
        value:
          type: string
          description: >-
            Field value as string. Phone fields require JSON:
            {"number":"123456789","country":"DE"}.
          example: John
    PostV1EnterprisesCompaniesRequest:
      type: object
      properties:
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        timezone:
          type: string
          description: Timezone.
          example: Europe/Berlin
        business_category:
          type: string
          description: Business category.
          example: example
        description:
          type: string
          description: Description.
          example: example
        phone:
          type: string
          description: Phone.
          example: 491701234567
        email:
          type: string
          format: email
          description: Email.
          example: alex@example.com
        owner_name:
          type: string
          description: Owner name.
          example: example
        address:
          type: object
          additionalProperties: true
          description: Address.
          example:
            key: value
        name:
          type: string
          description: Name.
          example: example
        locale:
          type: string
          description: Locale.
          example: active
        plan:
          type: string
          description: Plan.
          example: example
        workingtime:
          type: string
          description: Workingtime.
          example: '09:30'
        activate_online_booking:
          type: string
          description: Activate online booking.
          example: example
        region:
          type: string
          description: Region.
          example: active
        settings:
          type: object
          additionalProperties: true
          description: Settings.
          example:
            key: value
        metadata:
          type: object
          additionalProperties: true
          description: Metadata.
          example:
            key: value
      description: Request payload for `POST /v1/enterprises-companies`.
      required:
        - email
        - owner_name
        - name
        - locale
        - plan
    PostV1EnterprisesCompaniesDeleteBulkRequest:
      type: object
      properties:
        company_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Company ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        deletion_secret:
          type: string
          description: Deletion secret.
          example: example
      description: Request payload for `POST /v1/enterprises-companies/delete/bulk`.
    PostV1EnterprisesCompaniesGenerateSecretRequest:
      type: object
      properties:
        buffer_hours:
          type: string
          description: Buffer hours.
          example: example
      description: Request payload for `POST /v1/enterprises-companies/generate-secret`.
    PutV1EnterprisesCompaniesByCompanyidOnlinestatusRequest:
      type: object
      properties:
        region:
          type: string
          description: Region.
          example: active
      description: >-
        Request payload for `PUT
        /v1/enterprises-companies/{companyId}/onlinestatus`.
    PatchV1EnterprisesCompaniesByIdRequest:
      type: object
      properties:
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        timezone:
          type: string
          description: Timezone.
          example: Europe/Berlin
        business_category:
          type: string
          description: Business category.
          example: example
        description:
          type: string
          description: Description.
          example: example
        phone:
          type: string
          description: Phone.
          example: 491701234567
        owner_name:
          type: string
          description: Owner name.
          example: example
        address:
          type: object
          additionalProperties: true
          description: Address.
          example:
            key: value
        name:
          type: string
          description: Name.
          example: example
        locale:
          type: string
          description: Locale.
          example: active
        plan:
          type: string
          description: Plan.
          example: example
        workingtime:
          type: string
          description: Workingtime.
          example: '09:30'
        region:
          type: string
          description: Region.
          example: active
        settings:
          type: object
          additionalProperties: true
          description: Settings.
          example:
            key: value
        metadata:
          type: object
          additionalProperties: true
          description: Metadata.
          example:
            key: value
      description: Request payload for `PATCH /v1/enterprises-companies/{id}`.
    PatchV1EnterprisesSettingsRequest:
      type: object
      properties:
        services_allocation:
          type: string
          description: Services allocation.
          example: example
        availability_display_config:
          type: object
          additionalProperties: true
          description: Availability display config.
          example:
            key: value
      description: Request payload for `PATCH /v1/enterprises/settings`.
    PostV1EnterpriseFilesRequest:
      type: object
      properties:
        key:
          type: string
          description: Key.
          example: example
        url:
          type: string
          format: uri
          description: Url.
          example: https://example.com
      description: Request payload for `POST /v1/enterprise-files`.
    PostV1EnterprisePermissionsGroupsRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        icon:
          type: string
          description: Icon.
          example: example
        color:
          type: string
          description: Color.
          example: active
        permissions:
          type: string
          description: Permissions.
          example: example
        affected_branch_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        affected_branch_external_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch external ids.
          example:
            - 65f4c840b6f1a10012ab34cd
      description: Request payload for `POST /v1/enterprise-permissions/groups`.
    PatchV1EnterprisePermissionsGroupsByGroupidRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        icon:
          type: string
          description: Icon.
          example: example
        color:
          type: string
          description: Color.
          example: active
        permissions:
          type: string
          description: Permissions.
          example: example
        affected_branch_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        affected_branch_external_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch external ids.
          example:
            - 65f4c840b6f1a10012ab34cd
      description: Request payload for `PATCH /v1/enterprise-permissions/groups/{groupId}`.
    PostV1EnterpriseResourcesCategoriesRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        is_dependency:
          type: boolean
          description: Is dependency.
          example: true
      description: Request payload for `POST /v1/enterprise-resources/categories`.
      required:
        - name
    PatchV1EnterpriseResourcesCategoriesByCategoryidRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        is_dependency:
          type: boolean
          description: Is dependency.
          example: true
      description: >-
        Request payload for `PATCH
        /v1/enterprise-resources/categories/{categoryId}`.
      required:
        - name
    PostV1EnterpriseServicesRequest:
      type: object
      properties:
        is_bookable:
          type: boolean
          description: Is bookable.
          example: true
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        category_id:
          type: string
          description: Category id.
          example: 65f4c840b6f1a10012ab34cd
        description:
          type: string
          description: Description.
          example: example
        color:
          type: string
          description: Color.
          example: active
        duration:
          type: integer
          minimum: 0
          description: Duration.
          example: 20
        duration_before:
          type: integer
          minimum: 0
          description: Duration before.
          example: 20
        duration_after:
          type: integer
          minimum: 0
          description: Duration after.
          example: 20
        durations_pattern:
          type: array
          items:
            type: integer
            example: 15
          minItems: 1
          description: Durations pattern.
          example:
            - 15
        price:
          type: number
          minimum: 0
          description: Price.
          example: 19.9
        has_online_payment:
          type: boolean
          description: Has online payment.
          example: true
        is_stalled:
          type: boolean
          description: Is stalled.
          example: true
        is_payment_mandatory:
          type: boolean
          description: Is payment mandatory.
          example: true
        max_participants:
          type: integer
          minimum: 0
          description: Max participants.
          example: 20
        dependencies:
          type: string
          description: Dependencies.
          example: example
        affected_branch_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        affected_branch_external_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch external ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        customer_reminders_minutes:
          type: integer
          minimum: 0
          description: Customer reminders minutes.
          example: 20
        resource_reminders_minutes:
          type: integer
          minimum: 0
          description: Resource reminders minutes.
          example: 20
        is_combination:
          type: boolean
          description: Is combination.
          example: true
        combination_service_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Combination service ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        is_combination_price_overwritten:
          type: boolean
          description: Is combination price overwritten.
          example: true
        has_combination_same_resources_preference:
          type: boolean
          description: Has combination same resources preference.
          example: true
        calendar:
          type: string
          description: Calendar.
          example: example
        booking_limit:
          type: string
          description: Booking limit.
          example: example
        disable_booking_limit:
          type: string
          description: Disable booking limit.
          example: example
        maximum_lead_time:
          type: string
          description: Maximum lead time.
          example: '09:30'
        minimum_lead_time:
          type: string
          description: Minimum lead time.
          example: '09:30'
        cancellation_lead_time:
          type: string
          description: Cancellation lead time.
          example: '09:30'
        attributes:
          type: string
          description: Attributes.
          example: example
        location:
          type: object
          additionalProperties: true
          description: Location.
          example:
            key: value
      description: Request payload for `POST /v1/enterprise-services`.
      required:
        - name
        - duration
        - durations_pattern
    PostV1EnterpriseServicesCategoriesRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        affected_branch_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        affected_branch_external_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch external ids.
          example:
            - 65f4c840b6f1a10012ab34cd
      description: Request payload for `POST /v1/enterprise-services/categories`.
    PatchV1EnterpriseServicesCategoriesByCategoryidRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        affected_branch_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        affected_branch_external_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch external ids.
          example:
            - 65f4c840b6f1a10012ab34cd
      description: >-
        Request payload for `PATCH
        /v1/enterprise-services/categories/{categoryId}`.
    PatchV1EnterpriseServicesByServiceidRequest:
      type: object
      properties:
        is_bookable:
          type: boolean
          description: Is bookable.
          example: true
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        category_id:
          type: string
          description: Category id.
          example: 65f4c840b6f1a10012ab34cd
        description:
          type: string
          description: Description.
          example: example
        color:
          type: string
          description: Color.
          example: active
        duration:
          type: integer
          minimum: 0
          description: Duration.
          example: 20
        duration_before:
          type: integer
          minimum: 0
          description: Duration before.
          example: 20
        duration_after:
          type: integer
          minimum: 0
          description: Duration after.
          example: 20
        durations_pattern:
          type: array
          items:
            type: integer
            example: 15
          minItems: 1
          description: Durations pattern.
          example:
            - 15
        price:
          type: number
          minimum: 0
          description: Price.
          example: 19.9
        has_online_payment:
          type: boolean
          description: Has online payment.
          example: true
        is_stalled:
          type: boolean
          description: Is stalled.
          example: true
        is_payment_mandatory:
          type: boolean
          description: Is payment mandatory.
          example: true
        max_participants:
          type: integer
          minimum: 0
          description: Max participants.
          example: 20
        dependencies:
          type: string
          description: Dependencies.
          example: example
        affected_branch_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        affected_branch_external_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch external ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        customer_reminders_minutes:
          type: integer
          minimum: 0
          description: Customer reminders minutes.
          example: 20
        resource_reminders_minutes:
          type: integer
          minimum: 0
          description: Resource reminders minutes.
          example: 20
        is_combination:
          type: boolean
          description: Is combination.
          example: true
        combination_service_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Combination service ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        is_combination_price_overwritten:
          type: boolean
          description: Is combination price overwritten.
          example: true
        has_combination_same_resources_preference:
          type: boolean
          description: Has combination same resources preference.
          example: true
        calendar:
          type: string
          description: Calendar.
          example: example
        booking_limit:
          type: string
          description: Booking limit.
          example: example
        disable_booking_limit:
          type: string
          description: Disable booking limit.
          example: example
        maximum_lead_time:
          type: string
          description: Maximum lead time.
          example: '09:30'
        minimum_lead_time:
          type: string
          description: Minimum lead time.
          example: '09:30'
        cancellation_lead_time:
          type: string
          description: Cancellation lead time.
          example: '09:30'
        attributes:
          type: string
          description: Attributes.
          example: example
        location:
          type: object
          additionalProperties: true
          description: Location.
          example:
            key: value
      description: Request payload for `PATCH /v1/enterprise-services/{serviceId}`.
      required:
        - name
        - duration
        - durations_pattern
    PostV1EnterpriseTagsRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        color:
          type: string
          description: Color.
          example: active
        note:
          type: string
          description: Note.
          example: example
        order_index:
          type: string
          description: Order index.
          example: example
        for_appointments:
          type: string
          description: For appointments.
          example: example
        for_customers:
          type: string
          description: For customers.
          example: example
      description: Request payload for `POST /v1/enterprise-tags`.
      required:
        - name
        - color
    PatchV1EnterpriseTagsByTagidRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        color:
          type: string
          description: Color.
          example: active
        note:
          type: string
          description: Note.
          example: example
      description: Request payload for `PATCH /v1/enterprise-tags/{tagId}`.
    PostV1FilesRequest:
      type: object
      properties:
        key:
          type: string
          description: Key.
          example: example
        url:
          type: string
          format: uri
          description: Url.
          example: https://example.com
      description: Request payload for `POST /v1/files`.
    PostV1GroupServicesRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        category_id:
          type: string
          description: Category id.
          example: 65f4c840b6f1a10012ab34cd
        description:
          type: string
          description: Description.
          example: example
        color:
          type: string
          description: Color.
          example: active
        duration:
          type: integer
          minimum: 0
          description: Duration.
          example: 20
        duration_before:
          type: integer
          minimum: 0
          description: Duration before.
          example: 20
        duration_after:
          type: integer
          minimum: 0
          description: Duration after.
          example: 20
        durations_pattern:
          type: array
          items:
            type: integer
            example: 15
          minItems: 1
          description: Durations pattern.
          example:
            - 15
        price:
          type: number
          minimum: 0
          description: Price.
          example: 19.9
        has_online_payment:
          type: boolean
          description: Has online payment.
          example: true
        is_bookable:
          type: boolean
          description: Is bookable.
          example: true
        is_stalled:
          type: boolean
          description: Is stalled.
          example: true
        is_payment_mandatory:
          type: boolean
          description: Is payment mandatory.
          example: true
        max_participants:
          type: integer
          minimum: 0
          description: Max participants.
          example: 20
        dependencies:
          type: string
          description: Dependencies.
          example: example
        maximum_lead_time:
          type: string
          description: Maximum lead time.
          example: '09:30'
        minimum_lead_time:
          type: string
          description: Minimum lead time.
          example: '09:30'
        cancellation_lead_time:
          type: string
          description: Cancellation lead time.
          example: '09:30'
        attributes:
          type: string
          description: Attributes.
          example: example
        extra_persons:
          type: string
          description: Extra persons.
          example: example
        location:
          type: object
          additionalProperties: true
          description: Location.
          example:
            key: value
      description: Request payload for `POST /v1/group-services`.
      required:
        - name
        - duration
        - durations_pattern
    PostV1GroupServicesCategoriesRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
      description: Request payload for `POST /v1/group-services/categories`.
    PatchV1GroupServicesCategoriesByCategoryidRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
      description: Request payload for `PATCH /v1/group-services/categories/{categoryId}`.
    PatchV1GroupServicesByGroupserviceidRequest:
      type: object
      properties:
        has_online_payment:
          type: boolean
          description: Has online payment.
          example: true
        is_bookable:
          type: boolean
          description: Is bookable.
          example: true
        is_stalled:
          type: boolean
          description: Is stalled.
          example: true
        is_payment_mandatory:
          type: boolean
          description: Is payment mandatory.
          example: true
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        category_id:
          type: string
          description: Category id.
          example: 65f4c840b6f1a10012ab34cd
        description:
          type: string
          description: Description.
          example: example
        color:
          type: string
          description: Color.
          example: active
        duration:
          type: integer
          minimum: 0
          description: Duration.
          example: 20
        duration_before:
          type: integer
          minimum: 0
          description: Duration before.
          example: 20
        duration_after:
          type: integer
          minimum: 0
          description: Duration after.
          example: 20
        durations_pattern:
          type: array
          items:
            type: integer
            example: 15
          minItems: 1
          description: Durations pattern.
          example:
            - 15
        price:
          type: number
          minimum: 0
          description: Price.
          example: 19.9
        max_participants:
          type: integer
          minimum: 0
          description: Max participants.
          example: 20
        dependencies:
          type: string
          description: Dependencies.
          example: example
        maximum_lead_time:
          type: string
          description: Maximum lead time.
          example: '09:30'
        minimum_lead_time:
          type: string
          description: Minimum lead time.
          example: '09:30'
        cancellation_lead_time:
          type: string
          description: Cancellation lead time.
          example: '09:30'
        attributes:
          type: string
          description: Attributes.
          example: example
        location:
          type: object
          additionalProperties: true
          description: Location.
          example:
            key: value
      description: Request payload for `PATCH /v1/group-services/{groupServiceId}`.
      required:
        - name
    PostV1EnterpriseGroupServicesRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        category_id:
          type: string
          description: Category id.
          example: 65f4c840b6f1a10012ab34cd
        description:
          type: string
          description: Description.
          example: example
        color:
          type: string
          description: Color.
          example: active
        duration:
          type: integer
          minimum: 0
          description: Duration.
          example: 20
        duration_before:
          type: integer
          minimum: 0
          description: Duration before.
          example: 20
        duration_after:
          type: integer
          minimum: 0
          description: Duration after.
          example: 20
        durations_pattern:
          type: array
          items:
            type: integer
            example: 15
          minItems: 1
          description: Durations pattern.
          example:
            - 15
        price:
          type: number
          minimum: 0
          description: Price.
          example: 19.9
        has_online_payment:
          type: boolean
          description: Has online payment.
          example: true
        is_bookable:
          type: boolean
          description: Is bookable.
          example: true
        is_stalled:
          type: boolean
          description: Is stalled.
          example: true
        is_payment_mandatory:
          type: boolean
          description: Is payment mandatory.
          example: true
        max_participants:
          type: integer
          minimum: 0
          description: Max participants.
          example: 20
        dependencies:
          type: string
          description: Dependencies.
          example: example
        affected_branch_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        affected_branch_external_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch external ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        maximum_lead_time:
          type: string
          description: Maximum lead time.
          example: '09:30'
        minimum_lead_time:
          type: string
          description: Minimum lead time.
          example: '09:30'
        cancellation_lead_time:
          type: string
          description: Cancellation lead time.
          example: '09:30'
        attributes:
          type: string
          description: Attributes.
          example: example
        extra_persons:
          type: string
          description: Extra persons.
          example: example
        location:
          type: object
          additionalProperties: true
          description: Location.
          example:
            key: value
      description: Request payload for `POST /v1/enterprise-group-services`.
      required:
        - name
        - duration
        - durations_pattern
    PostV1EnterpriseGroupServicesCategoriesRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        affected_branch_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        affected_branch_external_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch external ids.
          example:
            - 65f4c840b6f1a10012ab34cd
      description: Request payload for `POST /v1/enterprise-group-services/categories`.
    PatchV1EnterpriseGroupServicesCategoriesByCategoryidRequest:
      type: object
      properties:
        affected_branch_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        affected_branch_external_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch external ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
      description: >-
        Request payload for `PATCH
        /v1/enterprise-group-services/categories/{categoryId}`.
    PatchV1EnterpriseGroupServicesByGroupserviceidRequest:
      type: object
      properties:
        has_online_payment:
          type: boolean
          description: Has online payment.
          example: true
        is_bookable:
          type: boolean
          description: Is bookable.
          example: true
        is_stalled:
          type: boolean
          description: Is stalled.
          example: true
        is_payment_mandatory:
          type: boolean
          description: Is payment mandatory.
          example: true
        affected_branch_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        affected_branch_external_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Affected branch external ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        category_id:
          type: string
          description: Category id.
          example: 65f4c840b6f1a10012ab34cd
        description:
          type: string
          description: Description.
          example: example
        color:
          type: string
          description: Color.
          example: active
        duration:
          type: integer
          minimum: 0
          description: Duration.
          example: 20
        duration_before:
          type: integer
          minimum: 0
          description: Duration before.
          example: 20
        duration_after:
          type: integer
          minimum: 0
          description: Duration after.
          example: 20
        durations_pattern:
          type: array
          items:
            type: integer
            example: 15
          minItems: 1
          description: Durations pattern.
          example:
            - 15
        price:
          type: number
          minimum: 0
          description: Price.
          example: 19.9
        max_participants:
          type: integer
          minimum: 0
          description: Max participants.
          example: 20
        dependencies:
          type: string
          description: Dependencies.
          example: example
        maximum_lead_time:
          type: string
          description: Maximum lead time.
          example: '09:30'
        minimum_lead_time:
          type: string
          description: Minimum lead time.
          example: '09:30'
        cancellation_lead_time:
          type: string
          description: Cancellation lead time.
          example: '09:30'
        attributes:
          type: string
          description: Attributes.
          example: example
        location:
          type: object
          additionalProperties: true
          description: Location.
          example:
            key: value
      description: >-
        Request payload for `PATCH
        /v1/enterprise-group-services/{groupServiceId}`.
      required:
        - name
    PostV1NotificationsRequest:
      type: object
      properties:
        to:
          type: string
          format: date
          description: End date of the timeshift (YYYY-MM-DD, inclusive).
          example: '2026-03-11'
        reply:
          type: string
          description: Reply.
          example: example
        locale:
          type: string
          description: Locale.
          example: active
        subject:
          type: string
          description: Subject.
          example: example
        title:
          type: string
          description: Title.
          example: example
        content:
          type: string
          description: Content.
          example: example
        table:
          type: string
          description: Table.
          example: example
        send_at:
          type: string
          description: Send at.
          example: example
        refs:
          type: string
          description: Refs.
          example: example
        attachments:
          type: string
          description: Attachments.
          example: example
      description: Request payload for `POST /v1/notifications`.
      required:
        - subject
        - title
        - content
        - refs
    PostV1IcsResourcesSubscriptionRequest:
      type: object
      properties:
        id:
          type: string
          description: Id.
          example: 65f4c840b6f1a10012ab34cd
        icsConfigStatus:
          type: string
          description: Icsconfigstatus.
          example: example
      description: Request payload for `POST /v1/ics/resources/subscription`.
    PostV1ResourcesRequest:
      type: object
      properties:
        skip_invitation:
          type: string
          description: Skip invitation.
          example: example
        name:
          type: string
          description: Name.
          example: example
        email:
          type: string
          format: email
          description: Email.
          example: alex@example.com
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        category_id:
          type: string
          description: Category id.
          example: 65f4c840b6f1a10012ab34cd
        category_external_id:
          type: string
          description: Category external id.
          example: 65f4c840b6f1a10012ab34cd
        color:
          type: string
          description: Color.
          example: active
        avatar_file:
          type: string
          description: Avatar file.
          example: example
        is_bookable:
          type: boolean
          description: Is bookable.
          example: true
        permissions:
          type: string
          description: Permissions.
          example: example
        is_admin:
          type: boolean
          description: Is admin.
          example: true
        booking_times:
          type: array
          description: Booking times.
          items:
            $ref: '#/components/schemas/TimeInterval'
        working_times:
          type: array
          description: Working times.
          items:
            $ref: '#/components/schemas/TimeInterval'
        permissions_group_id:
          type: string
          description: Permissions group id.
          example: 65f4c840b6f1a10012ab34cd
        attributes:
          type: string
          description: Attributes.
          example: example
        availabilityDisplayConfig:
          type: string
          description: Availabilitydisplayconfig.
          example: example
        timezone:
          type: string
          description: Timezone.
          example: Europe/Berlin
      description: Request payload for `POST /v1/resources`.
    PostV1ResourcesCategoriesRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        is_dependency:
          type: boolean
          description: Is dependency.
          example: true
      description: Request payload for `POST /v1/resources/categories`.
      required:
        - name
    PatchV1ResourcesCategoriesByCategoryidRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        is_dependency:
          type: boolean
          description: Is dependency.
          example: true
      description: Request payload for `PATCH /v1/resources/categories/{categoryId}`.
      required:
        - name
    PatchV1ResourcesByResourceidRequest:
      type: object
      properties:
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        name:
          type: string
          description: Name.
          example: example
        email:
          type: string
          format: email
          description: Email.
          example: alex@example.com
        category_id:
          type: string
          description: Category id.
          example: 65f4c840b6f1a10012ab34cd
        category_external_id:
          type: string
          description: Category external id.
          example: 65f4c840b6f1a10012ab34cd
        color:
          type: string
          description: Color.
          example: active
        avatar_file:
          type: string
          description: Avatar file.
          example: example
        is_bookable:
          type: boolean
          description: Is bookable.
          example: true
        permissions:
          type: string
          description: Permissions.
          example: example
        is_admin:
          type: boolean
          description: Is admin.
          example: true
        skip_invitation:
          type: string
          description: Skip invitation.
          example: example
        booking_times:
          type: array
          description: Booking times.
          items:
            $ref: '#/components/schemas/TimeInterval'
        working_times:
          type: array
          description: Working times.
          items:
            $ref: '#/components/schemas/TimeInterval'
        calendar:
          type: string
          description: Calendar.
          example: example
        permissions_group_id:
          type: string
          description: Permissions group id.
          example: 65f4c840b6f1a10012ab34cd
        attributes:
          type: string
          description: Attributes.
          example: example
        availabilityDisplayConfig:
          type: string
          description: Availabilitydisplayconfig.
          example: example
        timezone:
          type: string
          description: Timezone.
          example: Europe/Berlin
      description: Request payload for `PATCH /v1/resources/{resourceId}`.
    PatchV1ResourcesByResourceidSettingsRequest:
      type: object
      properties:
        settings:
          type: object
          additionalProperties: true
          description: Settings.
          example:
            key: value
        locale:
          type: string
          description: Locale.
          example: active
      description: Request payload for `PATCH /v1/resources/{resourceId}/settings`.
    AvailabilityResource:
      type: object
      description: A resource available for booking on the queried service.
      properties:
        id:
          type: string
          description: TIMIFY resource ID.
          example: 62ee11a91d66269c365407b1
        externalId:
          type: string
          nullable: true
          description: Your system's external resource ID.
        name:
          type: string
          description: Resource display name.
          example: KS
        categoryId:
          type: string
          description: Resource category ID.
          example: 62ee11a91d66269c365407b0
        categoryName:
          type: string
          description: Name of the resource's category.
          example: Stylists
        avatarUrl:
          type: string
          nullable: true
          description: URL to the resource's avatar image.
        orderIndex:
          type: integer
          description: Display sort order within its category.
          example: 1
    PostV1ServicesRequest:
      type: object
      properties:
        is_bookable:
          type: boolean
          description: Is bookable.
          example: true
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        category_id:
          type: string
          description: Category id.
          example: 65f4c840b6f1a10012ab34cd
        description:
          type: string
          description: Description.
          example: example
        color:
          type: string
          description: Color.
          example: active
        duration:
          type: integer
          minimum: 0
          description: Duration.
          example: 20
        duration_before:
          type: integer
          minimum: 0
          description: Duration before.
          example: 20
        duration_after:
          type: integer
          minimum: 0
          description: Duration after.
          example: 20
        durations_pattern:
          type: array
          items:
            type: integer
            example: 15
          minItems: 1
          description: Durations pattern.
          example:
            - 15
        price:
          type: number
          minimum: 0
          description: Price.
          example: 19.9
        has_online_payment:
          type: boolean
          description: Has online payment.
          example: true
        is_stalled:
          type: boolean
          description: Is stalled.
          example: true
        is_payment_mandatory:
          type: boolean
          description: Is payment mandatory.
          example: true
        max_participants:
          type: integer
          minimum: 0
          description: Max participants.
          example: 20
        dependencies:
          type: string
          description: Dependencies.
          example: example
        is_ghost:
          type: boolean
          description: Is ghost.
          example: true
        customer_reminders_minutes:
          type: integer
          minimum: 0
          description: Customer reminders minutes.
          example: 20
        resource_reminders_minutes:
          type: integer
          minimum: 0
          description: Resource reminders minutes.
          example: 20
        is_combination:
          type: boolean
          description: Is combination.
          example: true
        combination_service_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Combination service ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        is_combination_price_overwritten:
          type: boolean
          description: Is combination price overwritten.
          example: true
        has_combination_same_resources_preference:
          type: boolean
          description: Has combination same resources preference.
          example: true
        calendar:
          type: string
          description: Calendar.
          example: example
        booking_limit:
          type: string
          description: Booking limit.
          example: example
        disable_booking_limit:
          type: string
          description: Disable booking limit.
          example: example
        maximum_lead_time:
          type: string
          description: Maximum lead time.
          example: '09:30'
        minimum_lead_time:
          type: string
          description: Minimum lead time.
          example: '09:30'
        cancellation_lead_time:
          type: string
          description: Cancellation lead time.
          example: '09:30'
        attributes:
          type: string
          description: Attributes.
          example: example
        location:
          type: object
          additionalProperties: true
          description: Location.
          example:
            key: value
      description: Request payload for `POST /v1/services`.
      required:
        - name
        - duration
        - durations_pattern
        - combination_service_ids
    PostV1ServicesCategoriesRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
      description: Request payload for `POST /v1/services/categories`.
    PatchV1ServicesCategoriesByCategoryidRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
      description: Request payload for `PATCH /v1/services/categories/{categoryId}`.
    PatchV1ServicesByServiceidRequest:
      type: object
      properties:
        is_bookable:
          type: boolean
          description: Is bookable.
          example: true
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        category_id:
          type: string
          description: Category id.
          example: 65f4c840b6f1a10012ab34cd
        description:
          type: string
          description: Description.
          example: example
        color:
          type: string
          description: Color.
          example: active
        duration:
          type: integer
          minimum: 0
          description: Duration.
          example: 20
        duration_before:
          type: integer
          minimum: 0
          description: Duration before.
          example: 20
        duration_after:
          type: integer
          minimum: 0
          description: Duration after.
          example: 20
        durations_pattern:
          type: array
          items:
            type: integer
            example: 15
          minItems: 1
          description: Durations pattern.
          example:
            - 15
        price:
          type: number
          minimum: 0
          description: Price.
          example: 19.9
        has_online_payment:
          type: boolean
          description: Has online payment.
          example: true
        is_stalled:
          type: boolean
          description: Is stalled.
          example: true
        is_payment_mandatory:
          type: boolean
          description: Is payment mandatory.
          example: true
        max_participants:
          type: integer
          minimum: 0
          description: Max participants.
          example: 20
        dependencies:
          type: string
          description: Dependencies.
          example: example
        customer_reminders_minutes:
          type: integer
          minimum: 0
          description: Customer reminders minutes.
          example: 20
        resource_reminders_minutes:
          type: integer
          minimum: 0
          description: Resource reminders minutes.
          example: 20
        is_combination:
          type: boolean
          description: Is combination.
          example: true
        combination_service_ids:
          type: array
          items:
            type: string
            example: 65f4c840b6f1a10012ab34cd
          minItems: 1
          description: Combination service ids.
          example:
            - 65f4c840b6f1a10012ab34cd
        is_combination_price_overwritten:
          type: boolean
          description: Is combination price overwritten.
          example: true
        has_combination_same_resources_preference:
          type: boolean
          description: Has combination same resources preference.
          example: true
        calendar:
          type: string
          description: Calendar.
          example: example
        booking_limit:
          type: string
          description: Booking limit.
          example: example
        disable_booking_limit:
          type: string
          description: Disable booking limit.
          example: example
        maximum_lead_time:
          type: string
          description: Maximum lead time.
          example: '09:30'
        minimum_lead_time:
          type: string
          description: Minimum lead time.
          example: '09:30'
        cancellation_lead_time:
          type: string
          description: Cancellation lead time.
          example: '09:30'
        attributes:
          type: string
          description: Attributes.
          example: example
        location:
          type: object
          additionalProperties: true
          description: Location.
          example:
            key: value
      description: Request payload for `PATCH /v1/services/{serviceId}`.
    PostV1BranchTagsRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        color:
          type: string
          description: Color.
          example: active
        note:
          type: string
          description: Note.
          example: example
      description: Request payload for `POST /v1/branch-tags`.
      required:
        - name
        - color
    PatchV1BranchTagsByTagidRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        external_id:
          type: string
          description: External id.
          example: 65f4c840b6f1a10012ab34cd
        color:
          type: string
          description: Color.
          example: active
        note:
          type: string
          description: Note.
          example: example
      description: Request payload for `PATCH /v1/branch-tags/{tagId}`.
    PostV1TagsRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        color:
          type: string
          description: Color.
          example: active
        note:
          type: string
          description: Note.
          example: example
        order_index:
          type: string
          description: Order index.
          example: example
        for_appointments:
          type: string
          description: For appointments.
          example: example
        for_customers:
          type: string
          description: For customers.
          example: example
      description: Request payload for `POST /v1/tags`.
      required:
        - name
        - color
    PatchV1TagsByTagidRequest:
      type: object
      properties:
        name:
          type: string
          description: Name.
          example: example
        color:
          type: string
          description: Color.
          example: active
        note:
          type: string
          description: Note.
          example: example
        order_index:
          type: string
          description: Order index.
          example: example
      description: Request payload for `PATCH /v1/tags/{tagId}`.
    TagReference:
      type: object
      description: Minimal tag reference embedded in resource objects.
      properties:
        id:
          type: string
          example: 646377d319354093d997f819
        name:
          type: string
          example: VIP CUSTOMER
    Tag:
      type: object
      description: A label that can be applied to customers and/or appointments.
      properties:
        id:
          type: string
          description: TIMIFY internal MongoDB ID of the tag.
          example: 646377d319354093d997f819
        name:
          type: string
          description: Display name of the tag.
          example: VIP CUSTOMER
        externalId:
          type: string
          nullable: true
          description: Your system's external identifier for this tag.
        color:
          type: string
          description: Hex color code.
          example: '#8ebec3'
        note:
          type: string
          nullable: true
          description: Optional internal note about the tag.
        isForCustomers:
          type: boolean
          description: Whether the tag can be applied to customers.
          example: true
        isForEvents:
          type: boolean
          description: Whether the tag can be applied to appointments.
          example: false
        customersCount:
          type: integer
          description: Number of customers with this tag.
          example: 12
        eventsCount:
          type: integer
          description: Number of appointments with this tag.
          example: 5
        orderIndex:
          type: integer
          description: Display sort order.
          example: 1
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 date-time when the tag was created.
          example: '2023-05-17T10:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 date-time when the tag was last updated.
          example: '2024-01-15T08:30:00.000Z'
        globalId:
          type: string
          nullable: true
          description: Enterprise-level global tag ID.
        isForAppointments:
          type: boolean
          description: >-
            Whether the tag can be applied to appointments (alias for
            isForEvents).
          example: true
        ts:
          type: integer
          nullable: true
          description: Unix timestamp of last update.
    PostV1TimeshiftsRequest:
      type: object
      properties:
        resource_id:
          type: string
          description: Resource id.
          example: 65f4c840b6f1a10012ab34cd
        external_resource_id:
          type: string
          description: External resource id.
          example: 65f4c840b6f1a10012ab34cd
        from:
          type: string
          format: date
          description: Start date of the timeshift (YYYY-MM-DD).
          example: '2026-03-10'
        to:
          type: string
          format: date
          description: End date of the timeshift (YYYY-MM-DD, inclusive).
          example: '2026-03-11'
        denial_times:
          type: array
          description: Denial times.
          items:
            $ref: '#/components/schemas/TimeInterval'
        working_times:
          type: array
          description: Working times.
          items:
            $ref: '#/components/schemas/TimeInterval'
        booking_times:
          type: array
          description: Booking times.
          items:
            $ref: '#/components/schemas/TimeInterval'
        denial_reason:
          type: string
          description: Reason for blocking the time (VACATION, SICK, BLOCKER, OTHER).
          enum:
            - VACATION
            - SICK
            - BLOCKER
            - OTHER
          example: VACATION
      description: Request payload for `POST /v1/timeshifts`.
    PostV1TimeshiftsImportBulkRequest:
      type: object
      properties:
        shifts:
          type: array
          description: Array of timeshift objects to create or update.
          items:
            type: object
            properties:
              resourceId:
                type: string
                example: 62ee11a91d66269c365407b1
              externalResourceId:
                type: string
              interval:
                $ref: '#/components/schemas/TimeInterval'
              workingTimes:
                type: array
                items:
                  $ref: '#/components/schemas/TimeInterval'
              bookingTimes:
                type: array
                items:
                  $ref: '#/components/schemas/TimeInterval'
              denialTimes:
                type: array
                items:
                  $ref: '#/components/schemas/TimeInterval'
              denialReason:
                type: string
                enum:
                  - VACATION
                  - SICK
                  - BLOCKER
                  - OTHER
        url:
          type: string
          format: uri
          description: Url.
          example: https://example.com
        secret:
          type: string
          description: Secret.
          example: example
        skip_emitter:
          type: string
          description: Skip emitter.
          example: example
      description: Request payload for `POST /v1/timeshifts/import/bulk`.
    PatchV1TimeshiftsByTimeshiftidRequest:
      type: object
      properties:
        resource_id:
          type: string
          description: Resource id.
          example: 65f4c840b6f1a10012ab34cd
        external_resource_id:
          type: string
          description: External resource id.
          example: 65f4c840b6f1a10012ab34cd
        from:
          type: string
          format: date
          description: Start date of the timeshift (YYYY-MM-DD).
          example: '2026-03-10'
        to:
          type: string
          format: date
          description: End date of the timeshift (YYYY-MM-DD, inclusive).
          example: '2026-03-11'
        denial_times:
          type: array
          description: Denial times.
          items:
            $ref: '#/components/schemas/TimeInterval'
        working_times:
          type: array
          description: Working times.
          items:
            $ref: '#/components/schemas/TimeInterval'
        booking_times:
          type: array
          description: Booking times.
          items:
            $ref: '#/components/schemas/TimeInterval'
        denial_reason:
          type: string
          description: Reason for blocking the time (VACATION, SICK, BLOCKER, OTHER).
          enum:
            - VACATION
            - SICK
            - BLOCKER
            - OTHER
          example: VACATION
      description: Request payload for `PATCH /v1/timeshifts/{timeshiftId}`.
    TimeInterval:
      type: object
      description: A time range with begin and end times.
      properties:
        begin:
          type: string
          description: Start time in HH:mm format.
          example: '08:00'
        end:
          type: string
          description: End time in HH:mm format.
          example: '17:00'
    WeeklyAllowancePlanDay:
      type: object
      description: Working/booking times configuration for a single weekday.
      properties:
        isActive:
          type: boolean
          description: Whether this day is active.
          example: true
        times:
          type: array
          items:
            type: object
            properties:
              beginTime:
                type: string
                description: Slot start time (HH:mm).
                example: '08:00'
              endTime:
                type: string
                description: Slot end time (HH:mm).
                example: '18:00'
    Timeshift:
      type: object
      description: A resource timeshift (schedule override for a date range).
      properties:
        id:
          type: string
          description: TIMIFY internal MongoDB ID.
          example: 65f4c840b6f1a10012ab34cd
        resourceId:
          type: string
          description: ID of the resource this timeshift belongs to.
          example: 62ee11a91d66269c365407b1
        days:
          type: array
          description: Dates covered by this timeshift.
          items:
            type: string
            format: date
          example:
            - '2026-03-10'
            - '2026-03-11'
        interval:
          $ref: '#/components/schemas/TimeInterval'
        workingTimes:
          type: array
          description: Working time intervals for these dates.
          items:
            $ref: '#/components/schemas/TimeInterval'
        bookingTimes:
          type: array
          description: Online booking time intervals for these dates.
          items:
            $ref: '#/components/schemas/TimeInterval'
        denialTimes:
          type: array
          description: Time intervals that are blocked/denied.
          items:
            $ref: '#/components/schemas/TimeInterval'
        denialReason:
          type: string
          description: Reason for blocking (VACATION, SICK, BLOCKER, OTHER).
          enum:
            - VACATION
            - SICK
            - BLOCKER
            - OTHER
          example: VACATION
        createdAt:
          type: string
          format: date-time
          description: ISO 8601 date-time when the timeshift was created.
          example: '2026-01-10T08:00:00.000Z'
        updatedAt:
          type: string
          format: date-time
          description: ISO 8601 date-time when the timeshift was last updated.
          example: '2026-01-10T08:00:00.000Z'
    CombinationService:
      type: object
      description: >-
        Service configuration for combination (multi-service) appointments. Each
        service in the combination must have its own service_id, duration, and
        optional resource assignments.
      properties:
        service_id:
          type: string
          pattern: ^[0-9a-f]{24}$
          description: ID of the service to include in the combination (MongoDB ObjectId).
          example: 65f4c840b6f1a10012ab34cd
        resource_ids:
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{24}$
          minItems: 1
          description: >-
            List of resource IDs (MongoDB ObjectIds) to assign to this service.
            Optional—if provided, must be non-empty.
          example:
            - 65f4c840b6f1a10012ab34ce
        duration:
          type: integer
          minimum: 0
          multipleOf: 5
          description: >-
            Duration in minutes for this service. Must be divisible by 5 (e.g.,
            5, 10, 15, 20, ...).
          example: 30
      required:
        - service_id
        - duration
  responses:
    BadRequest:
      description: Invalid request payload, query, or route parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Missing, invalid, or expired credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Unexpected proxy or downstream GraphQL error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
