User Manager (REST)

You add users to a Relativity environment to provide individuals with access to it. After creating users, you can add them to groups and assign permissions to the groups in various workspaces. For more information, see Users in the Relativity Documentation site.

The User Manager API exposes endpoints that provide the following functionality:

  • Supports CRUD operations on users.
  • Helper endpoints for retrieving user types and groups to associate with users.
  • Helper endpoints for retrieving and querying on lists of users.

As a sample use case, you might use this API to implement a custom tool for importing users into Relativity. You could retrieve user information for display in a custom application.

You can also use the User Manager service through .NET. For more information, see User Manager (.NET).

Guidelines for the User Manager service

Review the following guidelines for the User Manager service.

URLs

The URLs for REST endpoints contain path parameters that you need to set before making a call:

  • Set the {versionNumber} placeholder to the version of the REST API that you want to use, using the format lowercase v and the version number, for example v1 or v2
  • Set other path parameters in the URLs to the Artifact ID of a given entity, for example setting {workspaceID} to the Artifact ID of a workspace.

    • Note: To indicate the admin-level context, set the {workspaceID} path parameter to -1.

For example, you can use the following URL to update a user:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/users/{userID}

Set the path parameters as follows:

  • {versionNumber} to the version of the service, such as v1.
  • {userID} to the Artifact ID of the user.

Client code sample

To use the User Manager service, send requests by making calls with the required HTTP methods. You can use the following .NET code as a sample client for creating a user.

Create a user

To create a new user, send a POST request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/users

To retrieve a list of available types to assign to a user, see Retrieve available types for users.

Retrieve metadata for a user

To retrieve basic or extended metadata for a user, send a GET request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/users/{userID}?{includeMetadata:bool}&{includeActions:bool}

Extended metadata includes operations that you have permissions to perform on the user. Set the query parameters in the URL to true for extended metadata:

  • includeMetadata
  • includeActions

The request body is empty.

The response for a read operation contains many of the same fields as a response for a create operation. See the descriptions in View field descriptions for a create response.

Retrieve settings for the current user

To retrieve settings or extended metadata for the current user, send a GET request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/users/me/settings?{includeMetadata:bool}&{includeActions:bool}

Extended metadata includes operations that you have permissions to perform on the user. Set the query parameters in the URL to true for extended metadata:

  • includeMetadata
  • includeActions

The request body is empty..

Update properties for a user

To update the properties of a user, send a PUT request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/users/{userID}

You can restrict the update of a user to the date that it was last modified by adding the LastModifiedOn field to the request.

The request for an update operation contains the same fields as a request for a create operation. See the descriptions in View field descriptions for a create request.

The response for an update operation contains many of the same fields as a response for a create operation. See the descriptions in View field descriptions for a create response.

Update settings for the current user

To update the settings for the current user, send a PUT request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/users/me/settings

You can restrict the settings update to the date that it was last modified by adding the LastModifiedOn field to the request.

Delete a user

To remove a user from Relativity, send a DELETE request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/users/{userID}

The request body is empty.

When the user is successfully deleted, the response returns the status code of 200. For more information, see HTTP status codes in Relativity REST APIs.

Helper endpoints for querying on users

The User Manager service exposes multiple helper endpoints that you can use to query for information about users. See the following sections:

Retrieve available types for users

To retrieve available types for users, send a GET request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/users/available-types

The default values are internal or external, but the Relativity UI supports adding any value. The type is used only for reference.

The request body is empty.

Query for groups to associate with users

Use this endpoint to query for groups to which you can add one or more of the specified users. Send a POST request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/users/query-eligible-groups

Retrieve information about the current user

To retrieve information about the current user, send a GET request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/workspaces/{workspaceID}/users/me

The request body is empty.

Retrieve all users in a workspace

To retrieve a list of all users in a workspace, send a GET request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/workspaces/{workspaceID}/all-users?{includeDeleted:bool}

The request body is empty.

Retrieve active users in a workspace

To retrieve a list of active users in a workspace, send a GET request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/workspaces/{workspaceID}/active-users?{includeCurrentUser:int}&{enforceChoiceLimitForUI:bool}

If the number of returned users exceeds the ChoiceLimitForUI setting, no users are returned.

The request body is empty.

Retrieve users in workspace with Relativity access

To retrieve users in a workspace with Relativity access, send a GET request to the following service URL:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/workspaces/{workspaceID}/users-with-access

The request body is empty.

Query for users in a workspace

To query for users in a workspace, send a POST request with a URL in the following format:

Copy 
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/workspaces/{workspaceID}/query-users