Users API

Manage the users and user groups within your organization.

Access requirements

To use APIs, you must have a Visier account. If you don't have an account, contact your administrator. To authenticate with Visier APIs, use OAuth 2.0 or basic authentication. For more information, see API Authentication.

Custom profiles with one of the following capability sets:

  • User Management (Read, API)
  • User Management (Write, API) required for creating, updating, and deleting

Reach out to your administrator for access.

Overview

In Visier, each person who accesses Visier needs a user account. Each user account is assigned different permissions and profiles that determine their data access and ability to use certain features in Visier. For more information about users and user groups, see User Management and User Groups.

Note: Tenants can have a maximum of 25,000 users, except free trial tenants, which have a maximum of 100 users. Embedded administrating tenants can have a maximum of 500,000 users across all tenants, with a maximum of 5,000 users per analytic tenant. These maximums are the default, however, contact Visier Technical Support to request limit adjustments.

Administrating tenants can perform actions on a single tenant using TargetTenantID or on multiple tenants in the same request using tenantCode.

  • The TargetTenantID request header defines the tenant that you're logged into. If defined, the API call executes from the specified tenant. If omitted, the default is the administrating tenant.
  • The tenantCode parameter defines the tenant to make changes to. In APIs that support many tenant codes, specify each tenantCode and omit TargetTenantID.

For more information about whether TargetTenantID or tenantCode is supported in an endpoint, see API Reference.

Tip: Visier recommends that administrating tenant users focus primarily on managing users at the administrating tenant level. These users likely belong directly to your organization, such as customer support, customer value managers, account executives, and customer success. These users work with clients to manage their day-to-day solution needs.

Users V1

With version 1 of this API, you can:

  • Add a new user
  • Delete a user
  • Make changes to existing user accounts
  • Retrieve a user's details
  • Retrieve a list of all users
  • Assign permissions to users
  • Remove permissions from users
  • Retrieve a list of all permissions
  • Retrieve all users that are assigned a specific permission
  • Assign permissions to user groups
  • Remove permissions from user groups
  • Retrieve a list of user groups
  • Retrieve all users assigned to a user group
  • Add users to user groups
  • Remove users from user groups
  • Retrieve the Application Logs
  • Retrieve the Data Security Report

Tip: If you submit API requests for changes that cause a project to publish to production, 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. For more information, see Projects API.

Users V2

With version 2 of the API, you can: 

  • Add new users in bulk
  • Update users in bulk
  • Delete users in bulk

Users V3

With version 3 of the API, you can: 

  • Update or insert (upsert) a user, including assigning user groups, permissions, and profiles to the user.

User Groups V2

Access requirements

Custom profiles with one of the following capability sets:

  • Security (Read, API) or User Group Management (Read, API) or User Management (Read, API)
  • Security (Write, API) or User Group Management (Write, API) or User Management (Write, API) required for creating, updating, and deleting

Reach out to your administrator for access.

With version 2 of the API, you can:

  • Retrieve a list of all user groups
  • Retrieve a user group's details
  • Create new user groups in bulk
  • Update user groups in bulk, such as changing the users and permissions assigned to a user group
  • Delete user groups in bulk
  • Manage user group visibility in features. For more information, see Change a user group's visibility.

Use correlation IDs in User Groups V2 API calls

In bulk requests to create or update objects, the batch is processed concurrently with no guaranteed response order, making it difficult to reconcile the response object with the objects in your request. For example, let's say you sent a bulk request for objects 1, 2, 3, 4, and 5. The response object might return successful results for objects 3, 5, and 1 and failure results for objects 4 and 2. Without an identifier to designate which request object belongs to which response object, it's difficult to make sense of the response.

You can optionally use the correlationId field to associate bulk request fields with their corresponding response fields. Correlation IDs are useful additions to a bulk request if the request does not already include UUIDs, which are unique identifiers. If defined in a GET request, the correlationIds query parameter limits the response to the user groups associated with the specified correlation IDs. You can specify multiple correlation IDs in the correlationIds parameter separated by commas; for example, correlationIds=123,abc,456.

Requirements:

  • Correlation IDs may be between 3 and 64 characters long and consist of alphanumeric characters, -, and _.
  • Each request element must have a unique correlation ID.
  • Cannot reuse a correlation ID in subsequent POST requests while the ID is still active. A correlation ID is active for 7 days after creation.

For more information about whether correlation IDs are supported in an endpoint, see API Reference.

Tip:  

  • If you submit API requests for changes that cause a project to publish to production, 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. For more information, see Projects API.
  • When assigning users to user groups in a project, the limit is 10,000 users per user group, except free trial tenants, which have a maximum of 100 users. These maximums are the default, however, contact Visier Technical Support to request limit adjustments.
  • You can assign up to 250 permissions per user group in a project. These maximums are the default, however, contact Visier Technical Support to request limit adjustments.
Get Started
Everything you need to know to get started with the Users API.
Code Samples
Selection of code samples that demonstrate the use of the Users API. Copy and edit these code samples to suit your needs.
API Authentication
Use OAuth 2.0 or basic authentication to access Visier's public APIs.
API Reference
Explore the full API reference documentation.

More security around data access management

Limited Availability

Visier has also implemented additional safeguards that further limit who can manage permissions, change user groups, and preview as other users. We recommend that you turn on this feature to ensure administrators cannot access additional data or give themselves a higher access level than they have been assigned.

If this feature is enabled, administrators will need access to all data, such as the Super Admin permission, to perform the following actions:

  • Assign permissions.
  • Create and edit permissions.
  • Create and edit user groups.
  • Create and edit data access sets.
  • Create and edit security filters.
  • Preview the solution as a user.