

Last date modified: July 07 2025
In Relativity, choices are predetermined values of single and multi-choice list fields. You can perform operations on admin and workspace choices. For more general information, see
The Choice Manager service exposes multiple operations you can use to programmatically manage choices in your Relativity environment. It includes the following features:
As a sample use case, you could use the Choice Manager API to create choices used to perform specific operations in a custom application.
You can also use the Choice Manager API through .NET. For more information, see Choice Manager (.NET).
Review the following guidelines for working with this 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 retrieve a choice:
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/{ChoiceID}
Set the path parameters as follows:
You can use the Postman sample file to become familiar with making calls to endpoints on the Choice Manager service. To download the sample file, click Choice Manager Postman file.
To get started with Postman, complete these steps:
You can use the following .NET code as a sample client for creating a choice.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
public async Task<int> CreateChoiceRestAsync()
{
int choiceID = 0;
using (Relativity.ObjectModel.V1.Choice.IChoiceManager choiceManager = _serviceFactory.CreateProxy<Relativity.ObjectModel.V1.Choice.IChoiceManager>())
using (HttpClient client = new HttpClient())
{
client.DefaultRequestHeaders.Add("X-CSRF-Header", "-");
client.DefaultRequestHeaders.Add("Authorization", "Basic " + Convert.ToBase64String(Encoding.GetEncoding("ISO-8859-1").GetBytes("<user login>:<user password>")));
client.DefaultRequestHeaders.Add("X-Kepler-Version", "2.0");
client.BaseAddress = new Uri("http://localhost/");
string inputJSON = @"{""choiceRequest"":{""Field"":{""ArtifactID"":1104632,""Guids"":[]},""Name"":""Relevant"",""Color"":3,""Order"":100}}";
string url = "/Relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/1022092/choices";
HttpResponseMessage response = await client.PostAsync(url, new StringContent(inputJSON, Encoding.UTF8, "application/json"));
response.EnsureSuccessStatusCode();
string content = await response.Content.ReadAsStringAsync();
choiceID = Int32.Parse(content);
}
return choiceID;
}
To create a choice, send a POST request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices
The request must contain a choiceRequest object with the following fields:
1
2
3
4
5
6
7
8
9
10
11
{
"choiceRequest": {
"Field": {
"ArtifactID": 1104632,
"Guids": []
},
"Name": "Relevant",
"Color": 3,
"Order": 100
}
}
The response contains the Artifact ID of the created choice.
To create multiple choices in a mass operation, send a POST request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices
The request must contain a massCreateChoiceRequest 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
{
"massCreateChoiceRequest": {
"Choices": [
{
"Name": "Important",
"Children": [
{
"Name": "Critical"
},
{
"Name": "Very"
},
{
"Name": "Somewhat"
}
]
}
],
"ChoiceTemplateData": {
"Field": {
"ArtifactID": 1104635,
"Guids": []
}
}
}
}
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
{
"ChoicesCreated": [
{
"ObjectIdentifier": {
"Name": "Important",
"ArtifactID": 1104660,
"Guids": []
},
"ParentChoice": {
"ArtifactID": 0,
"Guids": []
}
},
{
"ObjectIdentifier": {
"Name": "Critical",
"ArtifactID": 1104661,
"Guids": []
},
"ParentChoice": {
"ArtifactID": 1104660,
"Guids": []
}
},
{
"ObjectIdentifier": {
"Name": "Very",
"ArtifactID": 1104662,
"Guids": []
},
"ParentChoice": {
"ArtifactID": 1104660,
"Guids": []
}
},
{
"ObjectIdentifier": {
"Name": "Somewhat",
"ArtifactID": 1104663,
"Guids": []
},
"ParentChoice": {
"ArtifactID": 1104660,
"Guids": []
}
}
],
"Success": true,
"Message": ""
}
To retrieve the metadata for a choice, send a GET request with a URL in the following format (to list the choices for a field, see Object Rule Manager service):
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/{ChoiceID}
The request body is empty.
The request contains the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
{
"ObjectIdentifier": {
"Name": "Critical",
"ArtifactID": 1104661,
"Guids": []
},
"Field": {
"Name": "Multi choice test field",
"ArtifactID": 1104635,
"Guids": []
},
"Order": 1000,
"Color": {
"ID": 3
},
"Parent": {
"ArtifactID": 1104660,
"Guids": []
}
}
To update a choice without a version check, send a PUT request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/{ChoiceID}
The request contains choiceRequest object with the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
{
"choiceRequest": {
"Name": "Critical - 2",
"Color": 3,
"Parent": {
"Name": "Important",
"ArtifactID": 1104636,
"Guids": []
},
"Order": 1000
}
}
When the choice is update successfully, the response contains a status code of 200.
To update a choice with a version check, send a PUT request with a URL in the following format::
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/{ChoiceID}
The request contains a choiceRequest object with the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
{
"choiceRequest": {
"Name": "Critical - 3",
"Color": 3,
"Parent": {
"Name": "Important",
"ArtifactID": 1104636,
"Guids": []
},
"Order": 400
},
"objectVersionToken": "637499580733130000"
}
When the choice is update successfully, the response contains a status code of 200.
To update multiple choices in a mass operation, send a PUT request with a URL in the following format
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices
All choices in a mass update request must be associated with the same field.
The request contains a massUpdateChoices object with an array of the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
{
"massUpdateChoices": [
{
"ObjectIdentifier": {
"ArtifactID": 1104662,
},
"Name": "Relevant",
"Color": 3
},
{
"ObjectIdentifier": {
"ArtifactID": 1104663,
},
"Name": "Confidential",
"Color": 3
}
]
}
The response contains the following fields:
1
2
3
4
5
{
"TotalChoices":2,
"Success":true,
"Message":""
}
To remove a choice from Relativity, send a DELETE request with a URL in the following format::
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/{ChoiceID}
When the choice is deleted successfully, the response contains a status code of 200.
To remove multiple choices in a mass operation, send a DELETE request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices
The request contains the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
{
"massDeleteRequest": {
"ChoiceIDs": [
{
"ArtifactID": 1104661,
},
{
"ArtifactID": 1104662,
},
{
"ArtifactID": 1104663,
}
]
}
}
The request contains the following fields:
1
2
3
4
5
{
"TotalChoices":3,
"Success":true,
"Message":""
}
When the choices are deleted successfully, the response contains a status code of 200.
To sort choices, send a PUT request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/sort
The request contains the following fields:
1
2
3
4
{
"fieldID": 1104635,
"sortType": "Ascending"
}
The response contains the following fields:
1
2
3
4
{
"TotalChoices": 16,
"Success": true
}
To move choices to the beginning or end of a list, send a PUT request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/move
The request contains the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
"fieldID": 1104635,
"choiceObjectIdentifiers": [
{
"ArtifactID": 1104638,
"Guids": []
},
{
"ArtifactID": 1104637,
"Guids": []
}
],
"moveListTo": "End"
}
The response contains the following fields:
1
2
3
4
5
{
"TotalChoices":0,
"Success":true,
"Message":""
}
To move choices after a specific choice in a list, send a PUT request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/move
The request contains the following fields:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
"fieldID": 1104635,
"choiceObjectIdentifiers": [
{
"ArtifactID": 1104638,
"Guids": []
},
{
"ArtifactID": 1104637,
"Guids": []
}
],
"choiceID": {
"ArtifactID": 1104651,
"Guids": []
}
}
The response contains the following fields:
1
2
3
4
5
{
"TotalChoices":0,
"Success":true,
"Message":""
}
You can retrieve a list of parents for a choice or a field.
To retrieve a list of available parents for a choice, send a GET request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/{ChoiceID}/parents
The request body is empty.
The response contains an array of identifier objects 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
[
{
"Name": "Important",
"ArtifactID": 1104636,
"Guids": []
},
{
"Name": "Very",
"ArtifactID": 1104637,
"Guids": []
},
{
"Name": "Somewhat",
"ArtifactID": 1104638,
"Guids": []
},
...
{
"Name": "Privileged",
"ArtifactID": 1104640,
"Guids": []
},
]
To retrieve a list of available parents for a specific field, send a POST request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/parents
The request contains a field identifier object with the following fields:
1
2
3
4
5
6
{
"fieldIdentifier": {
"ArtifactID":1104635,
"Guids":[]
}
}
The response contains an array of identifier objects 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
[
{
"Name": "Important",
"ArtifactID": 1104636,
"Guids": []
},
{
"Name": "Very",
"ArtifactID": 1104637,
"Guids": []
},
{
"Name": "Somewhat",
"ArtifactID": 1104638,
"Guids": []
},
...
{
"Name": "Privileged",
"ArtifactID": 1104640,
"Guids": []
},
]
To retrieve a list of available colors for highlighting a choice, send a GET request with a URL in the following format:
1
<host>/relativity.rest/api/relativity-object-model/{versionNumber}/workspaces/{workspaceID}/choices/colors
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
18
19
20
21
22
[
{
"Name": "Green",
"ID": 3
},
{
"Name": "Gray",
"ID": 12
},
{
"Name": "Blue",
"ID": 13
},
{
"Name": "Orange",
"ID": 14
},
{
"Name": "Tan",
"ID": 15
}
]
On this page
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 |