Choice Manager (.NET)

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 Choices in the Relativity Documentation site.

The Choice Manager API exposes multiple operations you can use to programmatically manage choices in your Relativity environment. It includes the following features:

  • Supports create, read, update, and delete operations and massive operations on choices.
  • Provides helper methods used to retrieve choice types and choice servers. Use these methods to determine if a server supports the choice type that you want to add to it.

A sample use case for the Choice Manager API service is a custom application that includes choices you want to perform operations with.

You can also use the Choice Manager service through the REST API. For more information, see Choice Manager service.

This page contains the following information:

The Relativity.ObjectModel.SDK contains this API. For compatibility and package installation instructions, see Download the SDKs and NuGet packages.

Fundamentals for managing choices

Review the following information to learn about the Choice Manager service.

Guidelines and considerations

  • Multi-choice fields allow choices to be arranged in a hierarchical fashion. For instance a choice of Important might have child a choices of Critical. Selecting the child choice on a field (in the RDO layout) will also cause the parent choice to be selected.
  • Single-choice fields do not allow for this arrangement of choices. As such, some of the endpoints only apply to multi-choice fields, or choices that are associated with multi-choice fields. Examples of this are the GetAvailableParentListAsync() methods. Requests to these made to these endpoints that reference single-choice fields will result in a status code 422 (unprocessable entity) response. See the method description details below for which methods are multi-choice only.


The IChoiceManager interface in the Relativity.ObjectModel.<VersionNumber>.Choice namespace exposes the following methods:

Note: The <VersionNumber> variable indicates the version number of the API. The version number uses the format uppercase V and an integer version number, such as V1 in .NET.

  • CreateAsync() method - adds a new choice to a Relativity environment. It returns the Artifact ID of the new choice. To create a choice, pass a ChoiceRequest object to the method. To mass create choices, pass a MassCreateChoiceRequest object to the method. It returns a MassCreateChoiceResponse object.
  • ReadAsync() method - retrieves information about a choice. To retrieve a choice, pass a valid choice Artifact ID or GUID. It returns a ChoiceResponse object.
  • UpdateAsync() method - modifies one or more choices. To update a choice, pass a ChoiceRequest object and valid choice Artifact ID or GUID to the method. To mass update choices, pass a MassUpdateChoiceRequest object to the method. It returns a MassActionChoiceResponse object.
  • DeleteAsync() method - removes one or more choices from Relativity. To delete a choice, pass a valid choice Artifact ID or GUID to the method. To mass delete choices, pass a MassDeleteChoiceRequest object to the method. It returns a MassActionChoiceResponse object.
  • AvailableParentsListAsync() method - retrieves a list of available parents for a specific choice or field.
  • GetColorsListAsync() method - retrieves a list of colors that can be assigned to a choice.
  • SortAsync() method - sorts a list of choices. To alphabetically sort all choices in a field, pass a valid field Artifact ID and a ChoiceReorderTypeEnum object. It returns a MassActionChoiceResponse object.
  • MoveAsync() method - moves one or more choices in a list. To move a choice(s) to the beginning or end, pass a valid field Artifact ID, a list of ObjectIdentifier, and a ChoiceMoveTypeEnum object. To move a choice(s) after a specific choice, pass a valid field Artifact ID, a list of ObjectIfentifier, and an ObjectIdentifier object that represents the specific choice. It returns a MassActionChoiceResponse object.


The following classes are used by the Choice Manager API:

  • ChoiceRequest class - used to specify information for creating or updating a choice.
    • Field - identifies which field the choice is associated with.
    • Name - name of field.
    • Color - color of field.
    • Order - field order. Used to determine order in which multiple choices are listed in UI. Lower values are listed first.
  • ChoiceResponse class - represents the results of a read operation on a choice.
  • MassActionChoiceResponse class - represents the result summary of both a massive delete or a massive update of choices.
  • MassCreateChoiceRequest class - represents the request to create multiple choices at once.
    • Choices - list of choices to be created. For single choice fields this must be a flat list of choices (choices cannot have child choices). In the case of multi-choice fields the list can be hierarchical. Each choice can have child choices, each of which in turn can have their own child choices, etc. Note that it's only possible to specify the choice name property with mass create.
    • ChoiceTemplateData - information to be applied to all the created choices.
  • MassCreateChoiceResponse class - represents the result summary of both massive create choices.
  • MassDeleteChoiceRequest class - represents a request to delete multiple choices.
  • MassUpdateChoiceRequest class - represents data model for choice massive update request.


  • WorkspaceID - ArtifactID of the workspace containing the choice. Use -1 to refer to the admin workspace.
  • ChoiceID - the ArtifactID of the choice to update.
  • ChoiceGuid - the ArtifactGuid of the choice to update.
  • ObjectVersionToken - the version token of the choice being updated. The token is generated from the choice object's last-modified-on time stamp.
  • ChoiceObjectIdentifiers - Choices to be moved.
  • MoveListTo - an enumeration specifying whether to move the designated choices to the beginning or end of the list of choices under the field. Options are "Beginning" or "End".
  • SortType - an enumeration specifying the sort order (i.e., ascending or descending).
  • FieldIdentifier - the object identifier (ArtifactID or GUID) of the field for retrieving the parent choices.

Create a single choice

Mass create choices

Read a choice

Update a choice (no version check)

Update a choice (with version check)

Mass update choices

Delete a choice

Mass delete choices

Sort choices

Move choices to start or end of list

Move choices after a specific choice in a list

Retrieve a list of available parents

Retrieve a list of available colors

Additional Resources

DevHelp Community GitHub Release Notes NuGet

Share knowledge with the Relativity developer community.

Access tools and resources to build an application.

Review the most recent product release notes.

Create .NET Apps faster with NuGet.