Visier User Groups V2 API

openapi: 3.2.0
info:
  title: Visier Administration User Groups V2 API
  description: Visier APIs for managing your tenant or tenants in Visier. You can programmatically manage user accounts in Visier, the profiles and permissions assigned to users, and to make changes in projects and publish projects to production. Administrating tenant users can use administration APIs to manage their analytic tenants and consolidated analytics tenants.<br>**Note:** If you submit API requests for changes that cause a project to publish to production (such as assigning permissions to users or updating permissions), each request is individually published to production, resulting in hundreds or thousands of production versions. We recommend that you use the `ProjectID` request header to make changes in a project, if `ProjectID` is available for the API endpoint.
  license:
    name: Apache License, Version 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  version: 22222222.99201.3040
security:
- ApiKeyAuth: []
  BearerAuth: []
- ApiKeyAuth: []
  CookieAuth: []
- ApiKeyAuth: []
  OAuth2Auth: []
tags:
- name: UserGroupsV2
  x-displayName: User Groups V2
  description: Manage user groups in Visier, such as creating, updating, and deleting user groups in bulk.
paths:
  /v2/admin/user-groups:
    get:
      tags:
      - UserGroupsV2
      summary: Retrieve a list of user groups
      description: "Retrieve a collection of user groups. Use `with` to control the amount of detail returned in the response.\n `with` supports these values:\n * **permissions**: Include the user group's permissions.\n * **users**: Include the users in the user group.\n * **details**: Include all available information.\n\n This API can return a maximum of 1000 user groups. The default number of user groups to return is 100.\n\n To specify the project in which to return user groups, provide a project UUID in the `ProjectID` request header.\n\n <br>To specify the tenant in which to retrieve user groups, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header."
      operationId: UserGroupsV2_GetUserGroups
      parameters:
      - name: with
        in: query
        description: "Controls the amount of detail to return in the response. Omit to return basic information.\n * **permissions**: Include the user group's permissions.\n * **users**: Include the users in the user group.\n * **details**: Include all available information."
        schema:
          enum:
          - permissions
          - users
          - details
          type: string
          format: enum
      - name: limit
        in: query
        description: The number of results to return. The maximum number of user groups to retrieve is 1000. The default is 100.
        schema:
          type: integer
          format: uint32
      - name: start
        in: query
        description: The index to start retrieving results from, also known as offset. The index begins at 0.
        schema:
          type: integer
          format: uint32
      - name: displayNameFilter
        in: query
        description: "The display name filter to narrow the set of user groups to return. This filter must be defined using glob syntax with the following wildcards and is case-sensitive. The value in parentheses is the equivalent hex code, which is used when URL-encoding the filter string:\n - `'*'` (`%2A`) matches any sequence of characters.\n - `'?'` (`%3F`) matches a single character.\n - `' '` (`%20`) matches a space character.\n \n Example: \n - `Sales*` matches any user group that starts with \"Sales\".\n - `* ?egional * Office` is expressed as `%2A%20%3Fegional%20%2A%20Office` and can have many matches, such as \"Western Regional Support Office\"."
        schema:
          type: string
      - name: correlationIds
        in: query
        description: "If defined, `correlationIds` limits the response to the user groups associated with the specified correlation IDs.\n You can specify multiple correlation IDs in the `correlationIds` parameter separated by commas; for example, `correlationIds=123,abc,456`.\n\n **Note**:\n - Correlation IDs must be between 3 and 64 characters long and may only contain alphanumeric characters, underscores and hyphens.\n - Correlation IDs have a lifetime of up to 7 days after creation. After a correlation ID expires, you can only retrieve specific user groups using the user group ID.\n - Correlation IDs are optional during user group creation and are only applicable to those objects created with a defined correlation ID."
        schema:
          type: string
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      - name: ProjectID
        in: header
        description: Optionally, specify a project in which to make the request.
        schema:
          type: string
          format: uuid
      - name: NonVersioned
        in: header
        description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
        schema:
          type: boolean
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.UserGroupsChangeDTO'
    put:
      tags:
      - UserGroupsV2
      summary: Update multiple user groups
      description: "Update existing user groups. To specify the tenant in which to update a user group, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header or `tenantCode` for each user group in the request body.\n\n When updating user groups, the user group definition in your API call replaces the prior definition. You must provide the entire definition in the `PUT` call. If you omit values from the update request, those values are removed from the user group. We recommend that you retrieve a user group's details before you update the user group with new values. \n\n To specify the project in which to update user groups, provide a project UUID in the `ProjectID` request header or `projectId` for each user group in the request body."
      operationId: UserGroupsV2_PutUserGroups
      parameters:
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      - name: ProjectID
        in: header
        description: Optionally, specify a project in which to make the request.
        schema:
          type: string
          format: uuid
      - name: NonVersioned
        in: header
        description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/admin.UserGroupsChangeDTO'
        required: true
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.UserGroupChangeResponseDTO'
    post:
      tags:
      - UserGroupsV2
      summary: Create multiple user groups
      description: "Create new user groups. To specify the tenant in which to add new user groups, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header.\n\n To specify the project in which to create new user groups, provide a project UUID in the `ProjectID` request header or `projectId` for each user group in the request body."
      operationId: UserGroupsV2_CreateUserGroups
      parameters:
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      - name: ProjectID
        in: header
        description: Optionally, specify a project in which to make the request.
        schema:
          type: string
          format: uuid
      - name: NonVersioned
        in: header
        description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/admin.UserGroupsChangeDTO'
        required: true
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.UserGroupChangeResponseDTO'
    delete:
      tags:
      - UserGroupsV2
      summary: Delete multiple user groups
      description: "Delete user groups in bulk. To specify the tenant in which to delete user groups, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header.\n\n To specify the project in which to delete user groups, provide a project UUID in the `ProjectID` request header or `projectId` for each user group in the request body."
      operationId: UserGroupsV2_DeleteUserGroups
      parameters:
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      - name: ProjectID
        in: header
        description: Optionally, specify a project in which to make the request.
        schema:
          type: string
          format: uuid
      - name: NonVersioned
        in: header
        description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/admin.UserGroupsDeleteRequestDTO'
        required: true
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.UserGroupDeleteResponseDTO'
    patch:
      tags:
      - UserGroupsV2
      summary: Patch multiple user groups
      description: "Make partial changes to user groups. To specify the tenant in which to patch a user group, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header or `tenantCode` for each user group in the request body.\n\n Unlike `PUT`, which completely replaces the user group definition, use `PATCH` to change specific fields in the user group without affecting omitted fields.\n\n To specify the project in which to patch user groups, provide a project UUID in the `ProjectID` request header or `projectId` for each user group in the request body."
      operationId: UserGroupsV2_PatchUserGroups
      parameters:
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      - name: ProjectID
        in: header
        description: Optionally, specify a project in which to make the request.
        schema:
          type: string
          format: uuid
      - name: NonVersioned
        in: header
        description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
        schema:
          type: boolean
      - name: Prefer
        in: header
        description: 'When `NonVersioned: true`, use `Prefer` to optionally specify if API calls should be subject to locking. Locking prevents incremental changes in multiple API calls from overwriting each other. The `Prefer` header works alongside a tenant feature flag. When enabled, the default is `nvLock=global`. When disabled, the default is not to lock API calls. Contact Visier Technical Support to enable the tenant feature flag.

          Valid values for the `Prefer` header:

          * `nvLock=global`: Run API calls sequentially. Sequential API calls prevent calls from unintentionally overwriting each other.

          * `nvLock=artifact`: Allow API calls in parallel. Parallel API calls only work if the calls do not conflict with each other. If a change wasn''t applied, the request fails and returns the HTTP 409 conflict error. Run the request again until successful.

          * `nvLock=none`: Disable the global lock if the tenant feature flag is enabled.'
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/admin.UserGroupsChangeDTO'
        required: true
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.UserGroupChangeResponseDTO'
  /v2/admin/user-groups/revert-to-parent:
    post:
      tags:
      - UserGroupsV2
      summary: Revert user groups
      description: "Revert a user group to its parent version. For example, if you revert a:\n - Tenant override object: The object reverts to the Blueprint version or, for administrating tenants who revert an analytic tenant's object, the administrating tenant's object version.\n - Tenant object: The API request fails. The object is unique to your tenant and no parent version exists.\n - Blueprint object: Nothing happens. The object is inherited from the parent and there is nothing to revert on this tenant."
      operationId: UserGroupsV2_RevertUserGroupsToParent
      parameters:
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      - name: ProjectID
        in: header
        description: Optionally, specify a project in which to make the request.
        schema:
          type: string
          format: uuid
      - name: NonVersioned
        in: header
        description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/admin.UserGroupsRevertRequestDTO'
        required: true
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.UserGroupChangeResponseDTO'
  /v2/admin/user-groups/{userGroupId}:
    get:
      tags:
      - UserGroupsV2
      summary: Retrieve the details of a user group
      description: "Retrieve all available information about a specific user group.\n \n <br>To specify the tenant in which to retrieve a user group, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header.\n\n To specify the project in which to return a user group, provide a project UUID in the `ProjectID` request header."
      operationId: UserGroupsV2_GetUserGroup
      parameters:
      - name: userGroupId
        in: path
        description: The ID of user group.
        required: true
        schema:
          type: string
      - name: with
        in: query
        description: "Controls the amount of detail to return in the response. Omit to return detailed information.\n * **permissions**: Include the user group's permissions.\n * **users**: Include the users in the user group.\n * **details**: Include all available information."
        schema:
          enum:
          - permissions
          - users
          - details
          type: string
          format: enum
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      - name: ProjectID
        in: header
        description: Optionally, specify a project in which to make the request.
        schema:
          type: string
          format: uuid
      - name: NonVersioned
        in: header
        description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
        schema:
          type: boolean
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.UserGroupChangeDefinitionDTO'
    delete:
      tags:
      - UserGroupsV2
      summary: Delete a user group
      description: "Delete a specific user group. To specify the tenant in which to delete a user group, administrating tenants can provide an analytic tenant code in the `TargetTenantID` request header.\n\n To specify the project in which to delete a user group, provide a project UUID in the `ProjectID` request header."
      operationId: UserGroupsV2_DeleteUserGroup
      parameters:
      - name: userGroupId
        in: path
        description: The ID of user group to delete.
        required: true
        schema:
          type: string
      - name: TargetTenantID
        in: header
        description: Optionally, specify the tenant that you want to execute the API call on. This defines the tenant that you're logged into. If omitted, the request uses the administrating tenant as the login tenant.
        schema:
          type: string
      - name: ProjectID
        in: header
        description: Optionally, specify a project in which to make the request.
        schema:
          type: string
          format: uuid
      - name: NonVersioned
        in: header
        description: If `true`, the API call executes on non-versioned artifacts and create/update actions take effect without a new production version. If `false`, the API call executes on versioned artifacts and create/update actions release a new production version. Default is `false`.
        schema:
          type: boolean
      responses:
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/admin.UserGroupSingleDeleteResponseDTO'
components:
  schemas:
    admin.VisibleForSelectionDTO:
      type: object
      properties:
        enabled:
          type: boolean
          description: "If `true`, the user group is visible in features such as sharing an analysis with user groups or assigning user groups a Vee sample question. Cannot update to `true` if `features` is empty.\n If `false`, the user group is not visible to select in any features.\n Default is `true`."
        features:
          type: array
          items:
            enum:
            - AnalyticsFeatures
            - StudioFeatures
            type: string
            format: enum
          description: "The features in which the user group is visible. Default is empty.\n If `enabled` is `true`, the user group is visible in features listed.\n If `enabled` is `false`, this field is ignored."
    admin.UserGroupChangeDimensionFilterDTO:
      type: object
      properties:
        dimensionId:
          type: string
          description: The object name of the dimension.
        subjectReferencePath:
          allOf:
          - $ref: '#/components/schemas/admin.ElementIDsDTO'
          description: "A qualifying path if the dimension is from an analytic object that references Employee.\n For example, use `subjectReferencePath` to create a filter on the `Employment_Start_Type` dimension from the `Employment_Start` object, which references `Employee`: `{ \"ids\": [ \"Employee\", \"Employment_Start\" ] }`."
        memberSelections:
          type: array
          items:
            $ref: '#/components/schemas/admin.UserGroupChangeMemberSelectionDTO'
          description: The dimension members to select in the dynamic filter.
    admin.UserGroupFiltersDTO:
      type: object
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/admin.UserGroupChangeFilterDTO'
          description: The filters that define user group membership.
    admin.UserGroupDeleteFailureDTO:
      type: object
      properties:
        tenantCode:
          type: string
          description: The code of the tenant from which the user group could not be deleted.
        userGroupId:
          type: string
          description: The unique identifier of the user group that could not be deleted.
        message:
          type: string
          description: The error message containing the cause of the failure.
        rci:
          type: string
          description: The root cause identifier to provide to Visier Technical Support if you require further troubleshooting.
        projectId:
          type: string
          description: The ID of the project in which the user group could not be deleted.
    Status:
      type: object
      properties:
        localizedMessage:
          type: string
          description: Localized error message describing the root cause of the error.
        code:
          type: string
          description: Error classification.
        message:
          type: string
          description: Not used.
        rci:
          type: string
          description: Optional root cause identifier.
        userError:
          type: boolean
          description: Indicates whether the error is a user error.
      description: The response structure for errors.
    admin.UserGroupsDeleteRequestDTO:
      type: object
      properties:
        userGroups:
          type: array
          items:
            $ref: '#/components/schemas/admin.UserGroupDeleteDTO'
          description: The user groups to delete.
    admin.UserGroupChangeResponseDTO:
      type: object
      properties:
        successes:
          type: array
          items:
            $ref: '#/components/schemas/admin.UserGroupChangeSuccessDTO'
          description: The user groups that were successfully changed (created, updated, patched, or reverted).
        failures:
          type: array
          items:
            $ref: '#/components/schemas/admin.UserGroupChangeFailureDTO'
          description: The user groups that were not successfully changed (created, updated, patched, or reverted).
    admin.UserGroupsRevertRequestDTO:
      type: object
      properties:
        userGroups:
          type: array
          items:
            $ref: '#/components/schemas/admin.UserGroupRevertDTO'
          description: The user groups to revert.
    admin.UserGroupChangeUsersDTO:
      type: object
      properties:
        includeAllUsers:
          type: boolean
          description: "If `true`, all users are included in the user group. If `true`:\n * You can manually exclude users with `manuallyExcludedIds`.\n * Cannot be combined with `manuallyIncludedIds` or `dynamicFilterDefinition`."
        manuallyIncludedIds:
          allOf:
          - $ref: '#/components/schemas/admin.ElementIDsDTO'
          description: "Includes specified user IDs in the user group.\n * May be combined with `dynamicFilterDefinition`.\n * Omit if `includeAllUsers` is `true`."
        manuallyExcludedIds:
          allOf:
          - $ref: '#/components/schemas/admin.ElementIDsDTO'
          description: "Excludes specified user IDs from the user group.\n * You can manually exclude users if `includeAllUsers` is `true` or if `dynamicFilterDefinition` is defined.\n * Excluded IDs must not overlap with user IDs in `manuallyIncludedIds`."
        dynamicFilterDefinition:
          allOf:
          - $ref: '#/components/schemas/admin.UserGroupFiltersDTO'
          description: "The filters that dynamically define a population through dimensions or dimensions accessible through references from the analytic object.\n * Omit if `includeAllUsers` is `true`.\n * You can combine dynamic filters with manually-assigned users."
    admin.UserGroupChangeDefinitionDTO:
      type: object
      properties:
        userGroupId:
          type: string
          description: The unique identifier of the user group. Omit if creating a new user group.
        displayName:
          type: string
          description: An identifiable user group name to display in Visier, such as "Leadership User Group".
        description:
          type: string
          description: A detailed description of the population and purpose of the user group.
        permissionIds:
          allOf:
          - $ref: '#/components/schemas/admin.ElementIDsDTO'
          description: The unique identifiers of permissions assigned to members of this user group.
        users:
          allOf:
          - $ref: '#/components/schemas/admin.UserGroupChangeUsersDTO'
          description: The users assigned to the user group. You can define user group members dynamically with `dynamicFilterDefinition` or manually with `includeAllUsers` or `manuallyIncludedIds`.
        tenantCode:
          type: string
          description: "The code of the tenant to which the user group belongs or should be created in.\n Omit if creating or updating user groups in the current tenant."
        projectId:
          type: string
          description: "The project ID in which to update or create the user group.\n If omitted and the ProjectID request header is not defined, the change is published to production immediately."
        visibleForSelection:
          allOf:
          - $ref: '#/components/schemas/admin.VisibleForSelectionDTO'
          description: The features in which your users can see and select this user group. If omitted, the user group is visible in all features.
        correlationId:
          type: string
          description: "An optional identifier to associate bulk request fields with their corresponding response fields. Correlation IDs may be between 3 and 64 characters long and\n consist of alphanumeric characters, `-`, and `_`.\n\n **Note**:\n - Each request field must have a unique `correlationId`.\n - Cannot reuse a `correlationId` in subsequent POST requests while the ID is still active. A `correlationId` is active for 7 days after creation."
    admin.ElementIDsDTO:
      type: object
      properties:
        ids:
          type: array
          items:
            type: string
          description: The unique identifiers.
    admin.UserGroupRevertDTO:
      type: object
      properties:
        tenantCode:
          type: string
          description: "The code of the tenant in which to revert the user group.\n Omit if reverting user groups in the current tenant."
        userGroupId:
          type: string
          description: The unique identifier for the user group.
        projectId:
          type: string
          description: "The unique identifier of the project in which to revert the user group.\n If omitted and the `ProjectID` request header is not defined, the change is published to production immediately."
    admin.UserGroupDeleteSuccessDTO:
      type: object
      properties:
        tenantCode:
          type: string
          description: The code of the tenant the user group was deleted from.
        userGroupId:
          type: string
          description: The unique identifier of the user group that was deleted.
        projectId:
          type: string
          description: The ID of the project in which user group was deleted.
    admin.UserGroupsChangeDTO:
      type: object
      properties:
        userGroups:
          type: array
          items:
            $ref: '#/components/schemas/admin.UserGroupChangeDefinitionDTO'
          description: The user groups and their definitions.
    admin.UserGroupChangeFilterDTO:
      type: object
      properties:
        filterId:
          type: string
          description: The unique identifier of the filter. Omit if creating a new filter.
        analyticObjectId:
          type: string
          description: The analytic object the filter applies to. Currently, the only supported analytic object is `Employee`. Default is `Employee`.
        dimensionFilters:
          type: array
          items:
            $ref: '#/components/schemas/admin.UserGroupChangeDimensionFilterDTO'
          description: The dimensions in the dynamic filter.
    admin.UserGroupChangeSuccessDTO:
      type: object
      properties:
        displayName:
          type: string
          description: The display name of the user group that was successfully changed.
        userGroupId:
          type: string
          description: The unique identifier of the user group.
        tenantCode:
          type: string
          description: The code of the tenant in which the user group was changed.
        projectId:
          type: string
          description: The unique identifier of the project in which the user group was changed.
        correlationId:
          type: string
          description: An identifier to associate the matching request field. Only returned if a `correla

# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/visier/refs/heads/main/openapi/visier-usergroupsv2-api-openapi.yml