Create and update option sets using the Web API

Typically, you use global option sets to set fields so that different fields can share the same set of options, which are maintained in one location. Unlike local options sets which are defined only for a specific attribute, 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 organizations where your managed solution is installed. For more information, see Merge option set options.


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
Deletes one of the values in a global option set.
DeleteOptionValue Action
Inserts a new option into a global option set.
InsertOptionValue Action
Inserts a new option into the global option set used in the Status attribute.
InsertStatusValue Action
Changes the relative order of the options in an option set.
OrderOption Action
UpdateOptionSet Use PUT request with a OptionSetMetadata EntityType to [Organization URI]/api/data/v9.0/GlobalOptionSetDefinitions(metadataid)/Microsoft.Dynamics.CRM.OptionSetMetadata
For a local option set use [Organization URI]/api/data/v9.0/EntityDefinitions(metadataid)/Attributes(metadataid)/Microsoft.Dynamics.CRM.PicklistAttributeMetadata/OptionSet.
Updates an option in a global option set.
UpdateOptionValue Action
Inserts a new option into the option set used in the Status attribute.
UpdateStateValue Action

See also

Customize option sets