Create dictionary attribute definition.

post

https://api-us.bluestonepim.com/pim/definitions/dictionary

Create dictionary attribute definition. The new attribute definition's ID is generated by Bluestone PIM and is included in the response headers under resource-id.

Example: resource-id: 664cc80da825236207fe01a7

For more detailed information on how to work with attribute definitions in Bluestone PIM, refer to our help pages Create, edit or remove attributes and Attribute types - Dictionary.

Query Params

validation

string

enum

required

Validation strategy for the creation operation. Can be either NAME or NONE and defaults to NAME.

NAME means that a validation check will be performed to make sure that no other attribute definition exist with the same name.

NONE can be used to create an attribute definition with the same name as an other existing attribute definition. Note: The number must always be unique.

Allowed:

Body Params

contextAware

boolean

Indicates whether the attribute is context aware.

description

string

Details of the attribute definition.

dictionaryMetadataType

string

The type of metadata associated with the dictionary attribute.

externalSource

boolean

Specifies whether the origin of the attribute is managed in an external source like an ERP system or managed by a cloud function like an AWS Lambda or Azure Function and hence the attribute should be read-only for the editors in the Bluestone PIM web application UI.

Note: The value can still be modified via the Management API, for example by an integration or a cloud function triggered by a webhook message from Bluestone PIM.

groupId

string

The internal ID of the attribute group that the attribute definition belongs to.

Example: 634c26e14cedfd0001775e9f

internal

boolean

Indicates that the attribute is for internal use only within Bluestone PIM, meaning this value is not visible in the Public API (PAPI) for systems downstream of Bluestone PIM; for example, attributes for system configuration, enrichment workflows, or internal categorization.

name

string

Name of the attribute definition.

number

string

Number of the attribute definition. This value must be unique across all attribute definitions in Bluestone PIM. If not specified when creating the attribute definition, the system will use the attribute definition ID, which is a unique identifier generated by the system, as the default attribute definition number.

selectedValuesLimit

int32

The maximum number of selected values allowed for this dictionary attribute.

Headers

context

string

Specifies the context in which to operate. If omitted, the default context en is used.

In Bluestone PIM, the context is generally synonymous with the language setting. The context determines how product information is tailored and presented based on language or other local specifications.

For more detailed information on how context relates to language settings in Bluestone PIM, refer to the Languages and Context documentation.

Note: The default context is identified by the ID "en". IDs for additional contexts begin with a lowercase "L", not with the digit "1", followed by a number. This naming convention helps distinguish between default and custom contexts within Bluestone PIM.

Responses

201Created Note: The new ID is included in the response headers under resource-id. See the example below: Example: resource-id: 664cc80da825236207fe01a7

400Bad Request This response indicates that the server could not understand the request due to invalid syntax. It is typically triggered by client-side input errors such as improperly formatted requests, missing required fields, or invalid data values.

404Not Found This response indicates that the requested resource could not be found on the server. It typically occurs when no resource matches the requested URI, or the resource identifier used in the request does not exist.

409Conflict This response indicates that the request could not be completed due to a conflict with the current state of the target resource. This typically occurs when there are duplicate entries or other data conflicts.