Create and update choices (option sets) using the Web API

Note

Unsure about entity vs. table? See Developers: Understand terminology in Microsoft Dataverse.

Typically, you use global option sets to set table columns so that different columns can share the same set of options, which are maintained in one location. Unlike local option sets which are defined only for a specific column, you can reuse global option sets. You will also see them used in request parameters in a manner similar to an enumeration.

When you define a global option set using a POST request to [Organization URI]/api/data/v9.0/GlobalOptionSetDefinitions, we recommend that you let the system assign a value. You do this by passing a null value when you create the new OptionMetadata instance. When you define an option, it will contain an option value prefix specific to the context of the publisher set for the solution that the option set is created in. This prefix helps reduce the chance of creating duplicate option sets for a managed solution, and in any option sets that are defined in environments where your managed solution is installed. For more information, see Merge option set options.

Messages

The following table lists the messages that you can use with global option sets.

Message Web API Operation
CreateOptionSet Use POST request to [Organization URI]/api/data/v9.0/GlobalOptionSetDefinitions.
DeleteOptionSet Use DELETE request to [Organization URI]/api/data/v9.0/GlobalOptionSetDefinitions(metadataid).
RetrieveAllOptionSets Use GET request to [Organization URI]/api/data/v9.0/GlobalOptionSetDefinitions.
RetrieveOptionSet Use GET request to [Organization URI]/api/data/v9.0/GlobalOptionSetDefinitions(metadataid).

The following table lists the messages you can use with local and global option sets

Message Web API Operation
DeleteOptionValue

Deletes one of the values in a global option set.

DeleteOptionValue Action /
InsertOptionValue

Inserts a new option into a global option set.

InsertOptionValue Action /
InsertStatusValue

Inserts a new option into the global option set used in the Status column.

InsertStatusValue Action /
OrderOption

Changes the relative order of the options in an option set.

OrderOption Action /
UpdateOptionSet Use PUT request with a OptionSetMetadataBase EntityType / to [Organization URI]/api/data/v9.0/GlobalOptionSetDefinitions(metadataid)
Only those properties defined by the OptionSetMetadataBase can be updated. This does not include the options. Use other actions to make changes to options.
UpdateOptionValue

Updates an option in a global option set.

UpdateOptionValue Action /
UpdateStateValue

Inserts a new option into the option set used in the Status column.

UpdateStateValue Action /

See also

Customize choices