Skip to main content
POST
Create custom dimension definition

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

organizationId
string
required

String. The organization's internal ID (32-character hex string) or its externalSourceId. When the value matches the format of an internal ID, the internal ID takes precedence.

Example:

"11adfe2a080040e3892ffb89c21ec44e"

Body

application/json

At least one known property must be present. An empty body or a body with only unknown properties returns 400 INVALID_JSON_BODY or 400 NO_KNOWN_JSON_PROPERTIES respectively.

description
string

Display name of the custom dimension definition.

Maximum string length: 255
level
enum<string>

The scope at which this dimension is applied. Use INACTIVE to create the dimension in an inactive state.

Available options:
EXPENSE,
EXPENSE_REPORT,
INACTIVE
presetLocation
enum<string>

Where the preset value is defined. Defaults to no preset when omitted.

Available options:
NONE,
EMPLOYEE,
DEPARTMENT,
CATEGORY
controlType
enum<string>

Input type for the dimension. LIST and LIST_SEARCHABLE are both accepted and stored as a fixed list; the GET response always returns LIST for both.

Available options:
LIST,
LIST_SEARCHABLE,
TEXT
externalSourceId
string | null

Caller-supplied identifier used to address this definition from an external system.

Maximum string length: 255
useDateInterval
boolean | null

Whether the dimension value can be associated with a date interval.

recipientId
string | null

ID of the recipient to link to this dimension.

useAsRecipientFilter
boolean | null

Whether this dimension is used as a recipient filter.

hideDimensionValues
boolean | null

Whether the available dimension values are hidden from users.

usedInCarbonFootprint
boolean | null

Whether this dimension is used in carbon footprint calculations.

deviateOnCreditRow
boolean | null

Whether the dimension uses a deviating value on credit rows.

dimensionUsage
enum<string> | null

Describes how the dimension is used within the system. VATDimension links the dimension to VAT code values in accounting.

Available options:
Dimension,
VATDimension
userOverridable
boolean | null

When a preset is configured (presetLocation is not NONE), controls whether the user can override the preset value. Affects the computed visible field in the response.

visibleIfNoPreset
boolean | null

When no preset is configured (presetLocation is NONE), controls whether the dimension is shown to users. Affects the computed visible field in the response.

Response

Created — returns the newly created custom dimension definition

id
string
required

Unique internal identifier of the custom dimension definition.

description
string
required

Display name of the custom dimension definition.

status
enum<string>
required

Lifecycle status of the dimension definition.

Available options:
active,
inactive
level
enum<string>
required

The scope at which this dimension is applied.

Available options:
EXPENSE,
EXPENSE_REPORT
controlType
enum<string>
required

Input type for the dimension. LIST means a fixed list of values; TEXT means free-text input.

Available options:
LIST,
TEXT
useDateInterval
boolean
required

Whether the dimension value can be associated with a date interval.

visible
boolean
required

Computed visibility flag. true when the dimension is shown to users. Determined by presetLocation and user override settings.

externalSourceId
string | null

Caller-supplied identifier used to address this definition from an external system. Null when not set.

presetLocation
enum<string> | null

Where the preset value is defined. Null when no preset is configured.

Available options:
NONE,
EMPLOYEE,
DEPARTMENT,
CATEGORY
recipientId
string | null

ID of the recipient linked to this dimension. Null when not set.

useAsRecipientFilter
boolean | null

Whether this dimension is used as a recipient filter. Null when not configured.

hideDimensionValues
boolean | null

Whether the available dimension values are hidden from users. Null when not configured.

usedInCarbonFootprint
boolean | null

Whether this dimension is used in carbon footprint calculations. Null when not configured.

deviateOnCreditRow
boolean | null

Whether the dimension uses a deviating value on credit rows. Null when not configured.

deviatingCreditRowValue
object | null

The deviating dimension value applied on credit rows. Null when deviateOnCreditRow is false or not set.

dimensionUsage
string | null

Describes how the dimension is used within the system. Null when not configured.