Webex Mode Management API

openapi: 3.0.0
info:
  title: Webex Admin Address Book Mode Management API
  version: 1.0.0
  description: The Webex Admin APIs provide comprehensive programmatic access to administrative functions for managing Webex organizations, users, licenses, and settings. These APIs enable automation of user provisioning, license assignment, compliance management, and audit event retrieval. Administrators can integrate with enterprise identity systems, enforce security policies, monitor usage, and streamline onboarding/offboarding processes. The APIs support granular control over organizational resources, making them ideal for large-scale deployments and custom admin tooling.
tags:
- name: Mode Management
paths:
  /telephony/config/people/me/settings/modeManagement/features:
    get:
      tags:
      - Mode Management
      summary: Get Mode Management Features
      description: 'Retrieves a list of all mode management features (Auto Attendants, Call Queues, and Hunt Groups) for which the authenticated user has been designated as a mode manager. This API returns basic information about each feature including its ID, name, and type.


        Mode Management allows designated managers to switch features between different operational configurations based on time schedules or manual triggers. This is useful for managing business hours, holidays, and emergency scenarios.


        This API requires a user auth token with the `spark:telephony_config_read` scope. The authenticated user must be configured as a mode manager for at least one feature to receive results.'
      operationId: getModeManagementFeatures
      responses:
        '200':
          description: Mode management features retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModeManagementFeaturesResponse'
        '400':
          description: 'Bad Request: The request was invalid or cannot be otherwise served.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '423':
          description: Locked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '428':
          description: Precondition Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer-key: []
  /telephony/config/people/me/settings/modeManagement/features/commonModes:
    get:
      tags:
      - Mode Management
      summary: Get Common Modes
      description: 'Retrieves a list of common operating mode names that are shared across multiple specified features. This API accepts a list of feature IDs and returns only the mode names that exist in all of the specified features, allowing managers to switch multiple features to the same mode simultaneously.


        Common modes are useful when you need to coordinate operational changes across multiple features. For example, switching an entire office to "Holiday" mode across all Auto Attendants and Call Queues at once.


        This API requires a user auth token with the `spark:telephony_config_read` scope. The authenticated user must be a mode manager for the specified features.'
      operationId: getCommonModes
      parameters:
      - name: featureIds
        in: query
        description: List of feature IDs (comma-separated) for auto attendants, call queues, or hunt groups
        required: true
        schema:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 50
        style: form
        explode: false
        example:
        - Y2lzY29zcGFyazovL3VzL0ZFQVRVUkUvYjQzMmI2NmQtM2VkYy00ZGNkLTg4ODctNDZlOGU2NWQwYzIw
      responses:
        '200':
          description: Common modes retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CommonModesResponse'
        '400':
          description: 'Bad Request: The request was invalid or cannot be otherwise served.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '423':
          description: Locked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '428':
          description: Precondition Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer-key: []
  /telephony/config/people/me/settings/modeManagement/features/actions/switchMode/invoke:
    post:
      tags:
      - Mode Management
      summary: Switch Mode for Multiple Features
      description: 'Switches the operating mode for multiple features simultaneously by specifying a common mode name. This API accepts a list of feature IDs and sets all of them to the specified operating mode, provided that mode exists for all features.


        This bulk operation is particularly useful for coordinating operational changes across an organization, such as activating holiday modes, emergency procedures, or after-hours configurations across multiple Auto Attendants, Call Queues, and Hunt Groups at once.


        This API requires a user auth token with the `spark:telephony_config_write` scope. The authenticated user must be a mode manager for all specified features.'
      operationId: switchModeMultipleFeatures
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwitchModeMultipleFeaturesRequest'
      responses:
        '204':
          description: Mode switched successfully for multiple features
        '400':
          description: 'Bad Request: The request was invalid or cannot be otherwise served.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '423':
          description: Locked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '428':
          description: Precondition Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer-key: []
  /telephony/config/people/me/settings/modeManagement/features/{featureId}:
    get:
      tags:
      - Mode Management
      summary: Get Mode Management Feature
      description: 'Retrieves detailed information about a specific mode management feature including its current operating mode and exception status. This API provides the feature''s ID, name, type, current operating mode ID, and whether it is currently in an exception mode.


        Exception mode indicates that the feature has been manually switched to a different mode than what its schedule dictates. This information is critical for mode managers to understand the current state of their features.


        This API requires a user auth token with the `spark:telephony_config_read` scope. The authenticated user must be a mode manager for the specified feature.'
      operationId: getModeManagementFeature
      parameters:
      - name: featureId
        in: path
        description: Unique identifier for the feature.
        required: true
        schema:
          type: string
        example: Y2lzY29zcGFyazovL3VzL0ZFQVRVUkUvYjQzMmI2NmQtM2VkYy00ZGNkLTg4ODctNDZlOGU2NWQwYzIw
      responses:
        '200':
          description: Mode management feature retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModeManagementFeatureResponse'
        '400':
          description: 'Bad Request: The request was invalid or cannot be otherwise served.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '423':
          description: Locked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '428':
          description: Precondition Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer-key: []
  /telephony/config/people/me/settings/modeManagement/features/{featureId}/normalOperationMode:
    get:
      tags:
      - Mode Management
      summary: Get Normal Operation Mode
      description: 'Retrieves the current normal operating mode that the feature is scheduled to be in based on its time schedules. This represents the mode the feature would be in if no manual exceptions or overrides were active.


        The normal operation mode is determined by the feature''s configured schedules and may differ from the actual current operating mode if a manual exception has been applied. This API helps managers understand what the scheduled behavior is versus the actual current state.


        This API requires a user auth token with the `spark:telephony_config_read` scope. The authenticated user must be a mode manager for the specified feature.'
      operationId: getNormalOperationMode
      parameters:
      - name: featureId
        in: path
        description: Unique identifier for the feature.
        required: true
        schema:
          type: string
        example: Y2lzY29zcGFyazovL3VzL0ZFQVRVUkUvYjQzMmI2NmQtM2VkYy00ZGNkLTg4ODctNDZlOGU2NWQwYzIw
      responses:
        '200':
          description: Normal operation mode retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NormalOperationModeResponse'
        '400':
          description: 'Bad Request: The request was invalid or cannot be otherwise served.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '423':
          description: Locked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '428':
          description: Precondition Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer-key: []
  /telephony/config/people/me/settings/modeManagement/features/{featureId}/modes/{modeId}:
    get:
      tags:
      - Mode Management
      summary: Get Operating Mode
      description: 'Retrieves detailed information about a specific operating mode for a feature, including the mode''s ID and name. This API allows managers to get the details of any operating mode configured for a feature.


        Operating modes define different configurations for how a feature behaves (e.g., business hours routing vs. after-hours routing). Each mode has a unique ID and a descriptive name that helps managers identify its purpose.


        This API requires a user auth token with the `spark:telephony_config_read` scope. The authenticated user must be a mode manager for the specified feature.'
      operationId: getOperatingMode
      parameters:
      - name: featureId
        in: path
        description: Unique identifier for the feature.
        required: true
        schema:
          type: string
        example: Y2lzY29zcGFyazovL3VzL0ZFQVRVUkUvYjQzMmI2NmQtM2VkYy00ZGNkLTg4ODctNDZlOGU2NWQwYzIw
      - name: modeId
        in: path
        description: Unique identifier for the operating mode.
        required: true
        schema:
          type: string
        example: Y2lzY29zcGFyazovL3VzL09QRVJBVElOR19NT0RFLzAyZjZlMmI4LTFjZDktNWI3ZS1jOTVjLTczYzZkYzk1MTZjMg==
      responses:
        '200':
          description: Operating mode retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperatingModeResponse'
        '400':
          description: 'Bad Request: The request was invalid or cannot be otherwise served.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '423':
          description: Locked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '428':
          description: Precondition Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer-key: []
  /telephony/config/people/me/settings/modeManagement/features/{featureId}/actions/switchToNormalOperation/invoke:
    post:
      tags:
      - Mode Management
      summary: Switch to Normal Operation
      description: 'Switches the feature back to its normal scheduled operation mode, removing any manual exceptions or overrides that may be active. This returns the feature to operating according to its configured time schedules.


        This operation is useful when a temporary manual mode change (exception) is no longer needed and you want to restore automatic schedule-based operation. It effectively cancels any active manual mode switches.


        This API requires a user auth token with the `spark:telephony_config_write` scope. The authenticated user must be a mode manager for the specified feature.'
      operationId: switchToNormalOperation
      parameters:
      - name: featureId
        in: path
        description: Unique identifier for the feature.
        required: true
        schema:
          type: string
        example: Y2lzY29zcGFyazovL3VzL0ZFQVRVUkUvYjQzMmI2NmQtM2VkYy00ZGNkLTg4ODctNDZlOGU2NWQwYzIw
      responses:
        '204':
          description: Switched to normal operation successfully
        '400':
          description: 'Bad Request: The request was invalid or cannot be otherwise served.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '423':
          description: Locked
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '428':
          description: Precondition Required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: Bad Gateway
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: Gateway Timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - bearer-key: []
  /telephony/config/people/me/settings/modeManagement/features/{featureId}/actions/switchMode/invoke:
    post:
      tags:
      - Mode Management
      summary: Switch Mode for Single Feature
      description: 'Switches the operating mode for a single feature to a specified mode, either temporarily or with manual switchback. This API creates an exception to the feature''s normal scheduled operation, allowing managers to manually control the feature''s behavior.


        You can configure whether the mode switch is temporary (automatically reverts based on schedule) or requires manual switchback. This is useful for handling unexpected situations like emergency closures, special events, or unscheduled breaks.


        This API requires a user auth token with the `spark:telephony_config_write` scope. The authenticated user must be a mode manager for the specified feature.'
      operationId: switchModeForFeature
      parameters:
      - name: featureId
        in: path
        description: Unique identifier for the feature.
        required: true
        schema:
          type: string
        example: Y2lzY29zcGFyazovL3VzL0ZFQVRVUkUvYjQzMmI2NmQtM2VkYy00ZGNkLTg4ODctNDZlOGU2NWQwYzIw
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SwitchModeRequest'
      responses:
        '204':
          description: Mode switched successfully
        '400':
          description: 'Bad Request: The request was invalid or cannot be otherwise served.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '405':
          description: Method Not Allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorR

# --- truncated at 32 KB (68 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/webex/refs/heads/main/openapi/webex-mode-management-api-openapi.yml