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.UserGroupDeleteResponseDTO:
type: object
properties:
successes:
type: array
items:
$ref: '#/components/schemas/admin.UserGroupDeleteSuccessDTO'
description: The user groups that were successfully deleted.
failures:
type: array
items:
$ref: '#/components/schemas/admin.UserGroupDeleteFailureDTO'
description: The user groups that were not deleted successfully.
admin.UserGroupsDeleteRequestDTO:
type: object
properties:
userGroups:
type: array
items:
$ref: '#/components/schemas/admin.UserGroupDeleteDTO'
description: The user groups to delete.
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.
admin.ElementIDsDTO:
type: object
properties:
ids:
type: array
items:
type: string
description: The unique identifiers.
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.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.UserGroupsRevertRequestDTO:
type: object
properties:
userGroups:
type: array
items:
$ref: '#/components/schemas/admin.UserGroupRevertDTO'
description: The user groups to revert.
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.UserGroupChangeMemberSelectionDTO:
type: object
properties:
isExcluded:
type: boolean
description: If `true`, the specified member must not be defined for members of the user group.
namePath:
type: array
items:
type: string
description: The name path for dimension members; for example, `[ "North America", "US", "CA" ]`.
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 `correlationId` was defined for the corresponding request field.
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.UserGroupDeleteDTO:
type: object
properties:
tenantCode:
type: string
description: "The code of the tenant from which to delete the user group.\n Omit if deleting user groups in the current tenant."
userGroupId:
type: string
description: Unique identifier for the user group.
projectId:
type: string
description: "The project ID in which to delete the user group.\n If omitted and the `ProjectID` request header is not defined, the change is published to production immediately."
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.UserGroupChangeFailureDTO:
type: object
properties:
displayName:
type: string
description: The display name of the user group that couldn't be changed.
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.
tenantCode:
type: string
description: The code of the tenant in which the user group couldn't be changed.
projectId:
type: string
description: The unique identifier of the project in which the user group couldn't be changed.
userGroupId:
type: string
description: The unique identifier of the user group that couldn't be changed.
correlationId:
type: string
description: An identifier to associate the matching request field. Only returned if a `correlationId` was defined for the corresponding request field.
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.UserGroupFiltersDTO:
type: object
properties:
filters:
type: array
items:
$ref: '#/components/schemas/admin.UserGroupChangeFilterDTO'
description: The filters that define user group membership.
admin.UserGroupSingleDeleteResponseDTO:
type: object
properties:
success:
allOf:
- $ref: '#/components/schemas/admin.UserGroupDeleteSuccessDTO'
description: The user group was successfully deleted.
failure:
allOf:
# --- 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