

Last date modified: April 15 2025
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
The User Manager API exposes endpoints that provide the following functionality:
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).
Review the following guidelines for the User Manager service.
The URLs for REST endpoints contain path parameters that you need to set before making a call:
For example, you can use the following URL to update a user:
1
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/users/{userID}
Set the path parameters as follows:
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
public async Task<UserResponse> CreateUserAsync()
{
using (HttpClient client = new HttpClient())
{
client.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
client.DefaultRequestHeaders.Add("Authorization", "Basic " + Convert.ToBase64String(Encoding.GetEncoding("ISO-8859-1").GetBytes("test@test.com:SomePassword")));
client.DefaultRequestHeaders.Add("X-Kepler-Version", "2.0");
client.BaseAddress = new Uri("http://localhost/");
string inputJSON = "{\"UserRequest\":{\"AllowSettingsChange\": true,\"Client\": {\"Secured\": false,\"Value\": {\"ArtifactID\": 1015644}},\"DefaultFilterVisibility\": true,\"DocumentViewerProperties\": {\"AllowDocumentSkipPreferenceChange\": true,\"AllowDocumentViewerChange\": true,\"AllowKeyboardShortcuts\": true,\"DefaultSelectedFileType\": \"Default\",\"DocumentViewer\": \"Default\",\"SkipDefaultPreference\": true},\"DisableOnDate\": null,\"EmailAddress\": \"test222@relativity.com\",\"EmailPreference\": \"Default\",\"FirstName\": \"First Name\",\"ItemListPageLength\": 50,\"LastName\": \"Last Name\",\"RelativityAccess\": true,\"SavedSearchDefaultsToPublic\": true,\"TrustedIPs\": \"\",\"Type\": {\"ArtifactID\": 663},\"Keywords\": \"\",\"Notes\": \"\"}}";
string url = "/Relativity.REST/api/Relativity-Identity/{versionNumber}/users";
HttpResponseMessage response = await client.PostAsync(url, new StringContent(inputJSON, Encoding.UTF8, "application/json"));
response.EnsureSuccessStatusCode();
string content = await response.Content.ReadAsStringAsync();
return JsonConvert.DeserializeObject<UserResponse>(content);
}
}
To create a new user, send a POST request with a URL in the following format:
1
<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.
The body of the request must contain a UserRequest object with the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
"UserRequest":{
"AllowSettingsChange": true,
"Client": {
"Secured": false,
"Value": {
"ArtifactID": 1015644
}
},
"DefaultFilterVisibility": true,
"DocumentViewerProperties": {
"AllowDocumentSkipPreferenceChange": true,
"AllowDocumentViewerChange": true,
"AllowKeyboardShortcuts": true,
"DefaultSelectedFileType": "Default",
"DocumentViewer": "Default",
"SkipDefaultPreference": true
},
"DisableOnDate": null,
"EmailAddress": "email address",
"EmailPreference": "Default",
"FirstName": "First Name",
"ItemListPageLength": 50,
"LastName": "Last Name",
"RelativityAccess": true,
"SavedSearchDefaultsToPublic": true,
"TrustedIPs": "",
"Type": {
"ArtifactID": 663
},
"Keywords": "",
"Notes": ""
}
}
The response contains the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
{
"AllowSettingsChange":true,
"Client":{
"Secured":false,
"Value":{
"Name":"Relativity",
"ArtifactID":1015644,
"Guids":[
]
}
},
"DefaultFilterVisibility":true,
"DocumentViewerProperties":{
"AllowDocumentViewerChange":true,
"AllowKeyboardShortcuts":true,
"AllowDocumentSkipPreferenceChange":true,
"DefaultSelectedFileType":"Viewer",
"DocumentViewer":"Default",
"SkipDefaultPreference":true
},
"EmailAddress":"email address",
"EmailPreference":"All",
"FirstName":"First Name",
"ItemListPageLength":50,
"LastName":"Last Name",
"RelativityAccess":true,
"SavedSearchDefaultsToPublic":true,
"TrustedIPs":"",
"Type":{
"Name":"Internal",
"ArtifactID":663,
"Guids":[
]
},
"Keywords":"",
"Notes":"",
"CreatedOn":"2020-04-29T20:04:24.617",
"CreatedBy":{
"Name":"Doe, Jane",
"ArtifactID":1023652,
"Guids":[
]
},
"LastModifiedBy":{
"Name":"Doe, Jane",
"ArtifactID":1023652,
"Guids":[
]
},
"LastModifiedOn":"2020-04-29T20:04:24.617",
"Meta":{
"Unsupported":[
],
"ReadOnly":[
]
},
"Actions":[
{
"Name":"Delete",
"Href":"Relativity.Users/workspace/-1/users/1018403",
"Verb":"DELETE",
"IsAvailable":true,
"Reason":[
]
},
{
"Name":"Update",
"Href":"Relativity.Users/workspace/-1/users/1018403",
"Verb":"PUT",
"IsAvailable":true,
"Reason":[
]
}
],
"ArtifactID":1018403,
"Guids":[
]
}
To retrieve basic or extended metadata for a user, send a GET request with a URL in the following format:
1
<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:
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
"AllowSettingsChange":true,
"Client":{
"Secured":false,
"Value":{
"Name":"Relativity",
"ArtifactID":1015644,
"Guids":[
]
}
},
"DefaultFilterVisibility":true,
"DocumentViewerProperties":{
"AllowDocumentViewerChange":false,
"AllowKeyboardShortcuts":true,
"AllowDocumentSkipPreferenceChange":true,
"DefaultSelectedFileType":"Viewer",
"DocumentViewer":"Default",
"SkipDefaultPreference":true
},
"EmailAddress":"test@t.com",
"EmailPreference":"All",
"FirstName":"1",
"ItemListPageLength":25,
"LastName":"1",
"RelativityAccess":true,
"SavedSearchDefaultsToPublic":false,
"TrustedIPs":"",
"Type":{
"Name":"External",
"ArtifactID":672,
"Guids":[
]
},
"Keywords":"",
"Notes":"",
"CreatedOn":"2021-05-07T13:45:59.61",
"CreatedBy":{
"Name":"Allen, Rob",
"ArtifactID":9,
"Guids":[
]
},
"LastModifiedBy":{
"Name":"Allen, Rob",
"ArtifactID":9,
"Guids":[
]
},
"LastModifiedOn":"2021-05-07T13:45:59.61",
"Actions":[
],
"ArtifactID":1017952,
"Guids":[
]
}
To retrieve settings or extended metadata for the current user, send a GET request with a URL in the following format:
1
<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:
The request body is empty..
The response contains the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"Actions":[
],
"DefaultFilterVisibility":true,
"DefaultSelectedFileType":"Default",
"EmailAddress":"rob.allen@example.com",
"EmailPreference":"All",
"FirstName":"Rob",
"ItemListPageLength":25,
"LastName":"Allen",
"SavedSearchDefaultsToPublic":false,
"SkipDefaultPreference":false
}
To update the properties of a user, send a PUT request with a URL in the following format:
1
<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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
"UserRequest":{
"AllowSettingsChange":true,
"Client":{
"Secured":false,
"Value":{
"ArtifactID":1015644
}
},
"DefaultFilterVisibility":true,
"DocumentViewerProperties":{
"AllowDocumentSkipPreferenceChange":true,
"AllowDocumentViewerChange":true,
"AllowKeyboardShortcuts":true,
"DefaultSelectedFileType":"Default",
"DocumentViewer":"Default",
"SkipDefaultPreference":true
},
"DisableOnDate":null,
"EmailAddress":"email address",
"EmailPreference":"Default",
"FirstName":"First Name",
"ItemListPageLength":50,
"LastName":"Last Name",
"RelativityAccess":true,
"SavedSearchDefaultsToPublic":true,
"TrustedIPs":"",
"Type":{
"ArtifactID":663
},
"Keywords":"",
"Notes":""
}
}
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
{
"AllowSettingsChange":true,
"Client":{
"Secured":false,
"Value":{
"Name":"Relativity",
"ArtifactID":1015644,
"Guids":[
]
}
},
"DefaultFilterVisibility":true,
"DocumentViewerProperties":{
"AllowDocumentViewerChange":false,
"AllowKeyboardShortcuts":true,
"AllowDocumentSkipPreferenceChange":true,
"DefaultSelectedFileType":"Viewer",
"DocumentViewer":"Default",
"SkipDefaultPreference":true
},
"EmailAddress":"test@t.com",
"EmailPreference":"All",
"FirstName":"1",
"ItemListPageLength":25,
"LastName":"1",
"RelativityAccess":true,
"SavedSearchDefaultsToPublic":false,
"TrustedIPs":"",
"Type":{
"Name":"External",
"ArtifactID":672,
"Guids":[
]
},
"Keywords":"",
"Notes":"",
"CreatedOn":"2021-05-07T13:45:59.61",
"CreatedBy":{
"Name":"Allen, Rob",
"ArtifactID":9,
"Guids":[
]
},
"LastModifiedBy":{
"Name":"Allen, Rob",
"ArtifactID":9,
"Guids":[
]
},
"LastModifiedOn":"2021-05-07T13:45:59.61",
"Actions":[
],
"ArtifactID":1017952,
"Guids":[
]
}
To update the settings for the current user, send a PUT request with a URL in the following format:
1
<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.
The request must contain the following fields unless specifically identified as optional:
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"UserSettingRequest":{
"DefaultFilterVisibility":true,
"DefaultSelectedFileType":"Default",
"EmailAddress":"rob.allen@example.com",
"EmailPreference":"All",
"FirstName":"Rob",
"ItemListPageLength":25,
"LastName":"Allen",
"SavedSearchDefaultsToPublic":false,
"SkipDefaultPreference":false
}
}
The response contains the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
"Actions": [
{
"Name": "Delete",
"Href": "Relativity.Users/workspace/-1/users/1018403",
"Verb": "DELETE",
"IsAvailable": true,
"Reason": []
},
{
"Name": "Update",
"Href": "Relativity.Users/workspace/-1/users/1018403",
"Verb": "PUT",
"IsAvailable": true,
"Reason": []
}
],
"DefaultFilterVisibility": true,
"DefaultSelectedFileType": "LongText",
"EmailAddress": "email address",
"EmailPreference": "All",
"FirstName": "Updated First Name",
"ItemListPageLength": 10,
"LastName": "Updated Last Name",
"Meta": {
"Unsupported": [],
"ReadOnly": [
"Client",
"Email Address"
]
},
"SavedSearchDefaultsToPublic": false,
"SkipDefaultPreference": false
}
To remove a user from Relativity, send a DELETE request with a URL in the following format:
1
<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.
The User Manager service exposes multiple helper endpoints that you can use to query for information about users. See the following sections:
To retrieve available types for users, send a GET request with a URL in the following format:
1
<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.
The response contains the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
[
{
"Name":"Internal",
"ArtifactID":663,
"Guids":[
]
},
{
"Name":"External",
"ArtifactID":672,
"Guids":[
]
}
]
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:
1
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/users/query-eligible-groups
The JSON request should contain the following information:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"Users":[
{
"ArtifactID":9
}
],
"Request":{
"Condition":"",
"Sorts":[
{
"FieldIdentifier":{
"Name":"Name"
},
"Direction":"Ascending"
}
]
},
"Start":0,
"Length":25
}
The response contains the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
{
"TotalCount":6,
"Objects":[
{
"ArtifactID":1015025,
"Values":[
]
},
{
"ArtifactID":1015028,
"Values":[
]
},
{
"ArtifactID":1015029,
"Values":[
]
},
{
"ArtifactID":1015030,
"Values":[
]
},
{
"ArtifactID":1015026,
"Values":[
]
},
{
"ArtifactID":1015027,
"Values":[
]
}
],
"IDWindow":[
],
"CurrentStartIndex":0,
"ResultCount":6,
"ObjectType":{
"ArtifactID":1016185,
"Name":"Group",
"Guids":[
],
"ArtifactTypeID":3
},
"RankWindow":[
],
"Fields":[
]
}
To retrieve information about the current user, send a GET request with a URL in the following format:
1
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/workspaces/{workspaceID}/users/me
The request body is empty.
The response contains the following fields:
1
2
3
4
5
6
7
8
9
10
{
"FirstName": "Rob",
"LastName": "Allen",
"ItemListPageLength": 25,
"ShowFilters": true,
"CreatedOn": "2007-01-01T00:00:00",
"AclUserID": 9,
"ArtifactID": 9,
"Name": "Allen, Rob"
}
To retrieve a list of all users in a workspace, send a GET request with a URL in the following format:
1
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/workspaces/{workspaceID}/all-users?{includeDeleted:bool}
The request body is empty.
The response contains the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"LoggedInUserID":9,
"ActiveUsers":[
{
"ArtifactID":1017952,
"Name":"1, 1"
},
{
"ArtifactID":9,
"Name":"Allen, Rob"
},
{
"ArtifactID":777,
"Name":"Sidney, Robin"
}
]
}
To retrieve a list of active users in a workspace, send a GET request with a URL in the following format:
1
<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.
The response contains the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"LoggedInUserID":9,
"ActiveUsers":[
{
"ArtifactID":1017952,
"Name":"1, 1"
},
{
"ArtifactID":9,
"Name":"Allen, Rob"
},
{
"ArtifactID":777,
"Name":"Sidney, Robin"
}
]
}
To retrieve users in a workspace with Relativity access, send a GET request to the following service URL:
1
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/workspaces/{workspaceID}/users-with-access
The request body is empty.
The response contains the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"LoggedInUserID": 9,
"ActiveUsers": [
{
"ArtifactID": 9,
"Name": "Allen, Rob"
},
{
"ArtifactID": 777,
"Name": "Sidney, Robin"
},
{
"ArtifactID": 1017952,
"Name": "1, 1"
}
]
}
To query for users in a workspace, send a POST request with a URL in the following format:
1
<host>/Relativity.REST/api/Relativity-Identity/{versionNumber}/workspaces/{workspaceID}/query-users
The JSON request should contain the following information:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"Query":{
"Condition":"'User Type' IN ['Internal']",
"Sort":[
{
"FieldIdentifier":{
"Name":"FullName"
},
"Direction":"Ascending"
}
]
},
"Start":0,
"Length":25
}
The response contains the following fields unless specifically identified as optional:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
"DataResults":[
{
"ArtifactID":1023278,
"FullName":"Last Name, First Name",
"Email":"email address 1"
},
{
"ArtifactID":1032861,
"FullName":"Doe, Jane",
"Email":"email address 2"
},
{
"ArtifactID":1032943,
"FullName":"User, Test",
"Email":"email address 3"
}
],
"ResultCount":3,
"TotalResultCount":3,
"CurrentStartIndex":0
}
Why was this not helpful?
Check one that applies.
Thank you for your feedback.
Want to tell us more?
Great!
Additional Resources |
|||
DevHelp Community | GitHub | Release Notes | NuGet |