There are generally 3 APIs to be aware of when working with combo values. Each API covers slightly different use cases. Those use cases are outlined in this document.

CRUD on combo values

This is the most general use case, where an integration should manage the combo node definitions.

This requires the Editor_SystemTools_Metadata role.

There are 6 endpoints to be aware of here.

Response properties

Name	Type	Description

Name	Type	Description
`id`	int	A language-independent id for this combo value.
`optionValue`	string	A language-independent string value for this combo value.
`sortIndex`	int	A value indicating how this node should be sorted in relation to all other combo value.
`metaFieldId`	int	The metafield id of the metafield this combo value belongs to.
`itemId`	int	The itemId of the combo value.
`itemGuid`	string/guid/uuid	The itemGuid of the combo value.
`labels`	dictionary	The translations of this combo value. The key is the languageId.
`labels.label`	string	The title/name/label of the combo value in this language.
`labels.languageId`	int	The language id of this translation.
`labels.comboValueId`	int	The language specific id of this combo value.

Get all combo values

URL: /digizuitecore/legacyservice/api/admin/combo-values

Method: GET

Auth required: YES

Request

GET https://<my-dam>/digizuitecore/legacyservice/api/admin/combo-values
Authorization: AccessKey MIIC...dEK

Response

[
  {
    "id": 50239,
    "optionValue": "five",
    "sortIndex": 0,
    "metaFieldId": 50398,
    "itemId": 20460,
    "itemGuid": "8129443f-be24-4c48-9579-b8c91be41385",
    "labels": {
      "1": {
        "label": "fem",
        "languageId": 1,
        "comboValueId": 50239
      },
      "3": {
        "label": "five",
        "languageId": 3,
        "comboValueId": 50240
      }
    }
  }
]

Get a specific combo value

URL: /digizuitecore/legacyservice/api/admin/combo-values/{id}

Method: GET

Auth required: YES

Request

GET https://<my-dam>/digizuitecore/legacyservice/api/admin/combo-values/50239
Authorization: AccessKey MIIC...dEK

Response

Create a new combo value

URL: /digizuitecore/legacyservice/api/admin/combo-values

Method: POST

Auth required: YES

This api is also available as a bulk variant, that takes an array of the objects described here: /digizuitecore/legacyservice/api/admin/combo-values/bulk-create

Request parameters:

Name	Type	Description

Name	Type	Description
`optionValue`	string	A language-independent string value for this combo value.
`sortIndex`	int	A value indicating how this combo value should be sorted in relation to all other combo values.
`metaFieldId`	int	The metafield id of the metafield this combo valuebelongs to.
`accessRightsMode`	enum, string, one of: CalculateAutomatically DoNothing	Controls how access rights/item security is created when this combo value is created. CalculateAutomatically: Security is inherited from the metafield. DoNothing: No item security is created for this combo value, which means nobody can access it. If you use this, you should make sure to create item security entries yourself. If not specified, CalculateAutomatically will be used.
`labels`	array of object	The translations that should be created for this object.
`labels.languageId`	int	The id of the language this translation is for.
`labels.label`	string	The language specific translation of this value.

Request

Response

Update a combo value

URL: /digizuitecore/legacyservice/api/admin/combo-values/{comboId}

Method: PUT

Auth required: YES

Request parameters:

Name	Type	Description

Name	Type	Description
`optionValue`	string	A language-independent string value for this combo value.
`sortIndex`	int	A value indicating how this combo value should be sorted in relation to all other combo values.
`comboId`	int	A language-independent id for this combo value.

Request

Response

Update a combo value translation

URL: /digizuitecore/legacyservice/api/admin/combo-values/{comboId}/{languageId}

Method: PUT

Auth required: YES

Request parameters:

Name	Type	Description

Name	Type	Description
`label`	string	The translated label for the combo in the specified language.
`comboId`	int	The language-independent id for this combo value.
`languageId`	int	The id of the language to update the combo in

Request

Response

Delete a combo value

URL: /digizuitecore/legacyservice/api/admin/combo-values/{comboId}

Method: DELETE

Auth required: YES

Request parameters:

Name	Type	Description

Name

Type

Description

comboId

int

The language-independent id for this combo value.

synchronous

bool

If false or not passed, the value will be deleted in the background. This means you can still get the value back in the api and can still keep using it for a little while.

If true, the request will be held until the api is completely done cleaning up.

Get combos to display

URL:

/digizuitecore/legacyservice/api/combo/values/metafield/{metafieldId}
/digizuitecore/legacyservice/api/combo/values/metafield/{metafieldId}/assignable
/digizuitecore/legacyservice/api/combo/values/metafield/{metafieldItemGuid}
/digizuitecore/legacyservice/api/combo/values/metafield/{metafieldItemGuid}/assignable

Method: GET

Auth required: YES

This gets the combo nodes which the authorized user has access to based on item security. It is available in two flavors. One which returns everything the user has read access to and the /assignable variant of the endpoint which returns everything the user has write access to. The difference between the two is what the user can assign to an asset (i.e. write) and what the user can see as assigned on the asset (i.e. read).

Request parameters:

Name	Type	Description

Name	Type	Description
metafieldId	int	The metafield id of the tree metafield to fetch nodes for.
metafieldItemGuid	string/guid/uuid	The itemGuid of the tree metafield to fetch nodes for.

Response properties:

Name	Type	Description

Name	Type	Description
`id`	int	A language-independent id for this combo value.
`optionValue`	string	A language-independent string value for this combo value.
`sortIndex`	int	A value indicating how this node should be sorted in relation to all other combo value.
`metaFieldId`	int	The metafield id of the metafield this combo value belongs to.
`itemId`	int	The itemId of the combo value.
`itemGuid`	string/guid/uuid	The itemGuid of the combo value.
`labels`	dictionary	The translations of this combo value. The key is the languageId.
`labels.label`	string	The title/name/label of the combo value in this language.
`labels.languageId`	int	The language id of this translation.
`labels.comboValueId`	int	The language specific id of this combo value.

Create new combo nodes while updating asset metadata

See documentation and examples here: DC 5.9 Updating asset metadata | ComboValue request properties

Documentation

DC 5.9 Working with combo node definitions

CRUD on combo values

Get all combo values

Get a specific combo value

Create a new combo value

Update a combo value

Update a combo value translation

Delete a combo value

Get combos to display

Create new combo nodes while updating asset metadata