> ## Documentation Index
> Fetch the complete documentation index at: https://developer.findity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create custom dimension definition

> Creates a new custom dimension definition for the given organization. Returns 403 when the organization does not exist or the authenticated user is not an administrator of it.




## OpenAPI

````yaml /openapi/findity-admin-api.json post /organizations/{organizationId}/customdimensions
openapi: 3.1.0
info:
  title: Findity Admin API
  description: Findity Admin API
  version: 1.0.0
servers:
  - url: https://stage-api.findity.com/api/v1/admin
  - url: https://api.findity.com/api/v1/admin
security:
  - bearerAuth: []
paths:
  /organizations/{organizationId}/customdimensions:
    post:
      tags:
        - Dimensions
      summary: Create custom dimension definition
      description: >
        Creates a new custom dimension definition for the given organization.
        Returns 403 when the organization does not exist or the authenticated
        user is not an administrator of it.
      operationId: adminCreateCustomDimensionDefinition
      parameters:
        - name: organizationId
          in: path
          required: true
          description: >
            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.
          schema:
            type: string
            example: 11adfe2a080040e3892ffb89c21ec44e
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/AdminApiCustomDimensionDefinitionPostRequest
            example:
              description: Project
              level: EXPENSE
              controlType: LIST
              presetLocation: NONE
              externalSourceId: project
              visibleIfNoPreset: true
      responses:
        '201':
          description: Created — returns the newly created custom dimension definition
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminApiCustomDimensionDefinition'
              example:
                id: abc123def456abc123def456abc123de
                externalSourceId: project
                description: Project
                status: active
                level: EXPENSE
                presetLocation: NONE
                controlType: LIST
                useDateInterval: false
                recipientId: null
                useAsRecipientFilter: null
                hideDimensionValues: null
                usedInCarbonFootprint: false
                deviateOnCreditRow: false
                deviatingCreditRowValue: null
                dimensionUsage: null
                visible: true
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400Error'
              examples:
                Invalid JSON body:
                  value:
                    result: error
                    code: INVALID_JSON_BODY
                    description: Failed to parse json body.
                No known properties:
                  value:
                    result: error
                    code: NO_KNOWN_JSON_PROPERTIES
                    description: Request body contains no known properties
                Invalid property value:
                  value:
                    result: error
                    code: INVALID_JSON_PROPERTY_VALUE
                    description: >-
                      No enum constant
                      com.findity.economy.accounting.CustomDimensionDefinitionLevel.INVALID
        '403':
          description: Forbidden — organization not found or access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/403Error'
              examples:
                Organization not found or access denied:
                  value:
                    result: error
                    description: Organization not found or access denied
components:
  schemas:
    AdminApiCustomDimensionDefinitionPostRequest:
      type: object
      description: >
        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.
      properties:
        description:
          type: string
          description: Display name of the custom dimension definition.
          maxLength: 255
        level:
          type: string
          description: >
            The scope at which this dimension is applied. Use `INACTIVE` to
            create the dimension in an inactive state.
          enum:
            - EXPENSE
            - EXPENSE_REPORT
            - INACTIVE
        presetLocation:
          type: string
          description: >-
            Where the preset value is defined. Defaults to no preset when
            omitted.
          enum:
            - NONE
            - EMPLOYEE
            - DEPARTMENT
            - CATEGORY
        controlType:
          type: string
          description: >
            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.
          enum:
            - LIST
            - LIST_SEARCHABLE
            - TEXT
        externalSourceId:
          type: string
          description: >-
            Caller-supplied identifier used to address this definition from an
            external system.
          maxLength: 255
          nullable: true
        useDateInterval:
          type: boolean
          description: Whether the dimension value can be associated with a date interval.
          nullable: true
        recipientId:
          type: string
          description: ID of the recipient to link to this dimension.
          nullable: true
        useAsRecipientFilter:
          type: boolean
          description: Whether this dimension is used as a recipient filter.
          nullable: true
        hideDimensionValues:
          type: boolean
          description: Whether the available dimension values are hidden from users.
          nullable: true
        usedInCarbonFootprint:
          type: boolean
          description: Whether this dimension is used in carbon footprint calculations.
          nullable: true
        deviateOnCreditRow:
          type: boolean
          description: Whether the dimension uses a deviating value on credit rows.
          nullable: true
        dimensionUsage:
          type: string
          description: >-
            Describes how the dimension is used within the system.
            `VATDimension` links the dimension to VAT code values in accounting.
          enum:
            - Dimension
            - VATDimension
          nullable: true
        userOverridable:
          type: boolean
          description: >
            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.
          nullable: true
        visibleIfNoPreset:
          type: boolean
          description: >
            When no preset is configured (`presetLocation` is `NONE`), controls
            whether the dimension is shown to users. Affects the computed
            `visible` field in the response.
          nullable: true
    AdminApiCustomDimensionDefinition:
      type: object
      required:
        - id
        - description
        - status
        - level
        - controlType
        - useDateInterval
        - visible
      properties:
        id:
          type: string
          description: Unique internal identifier of the custom dimension definition.
        externalSourceId:
          type: string
          description: >-
            Caller-supplied identifier used to address this definition from an
            external system. Null when not set.
          nullable: true
        description:
          type: string
          description: Display name of the custom dimension definition.
        status:
          type: string
          description: Lifecycle status of the dimension definition.
          enum:
            - active
            - inactive
        level:
          type: string
          description: The scope at which this dimension is applied.
          enum:
            - EXPENSE
            - EXPENSE_REPORT
        presetLocation:
          type: string
          description: >-
            Where the preset value is defined. Null when no preset is
            configured.
          enum:
            - NONE
            - EMPLOYEE
            - DEPARTMENT
            - CATEGORY
          nullable: true
        controlType:
          type: string
          description: >-
            Input type for the dimension. `LIST` means a fixed list of values;
            `TEXT` means free-text input.
          enum:
            - LIST
            - TEXT
        useDateInterval:
          type: boolean
          description: Whether the dimension value can be associated with a date interval.
        recipientId:
          type: string
          description: ID of the recipient linked to this dimension. Null when not set.
          nullable: true
        useAsRecipientFilter:
          type: boolean
          description: >-
            Whether this dimension is used as a recipient filter. Null when not
            configured.
          nullable: true
        hideDimensionValues:
          type: boolean
          description: >-
            Whether the available dimension values are hidden from users. Null
            when not configured.
          nullable: true
        usedInCarbonFootprint:
          type: boolean
          description: >-
            Whether this dimension is used in carbon footprint calculations.
            Null when not configured.
          nullable: true
        deviateOnCreditRow:
          type: boolean
          description: >-
            Whether the dimension uses a deviating value on credit rows. Null
            when not configured.
          nullable: true
        deviatingCreditRowValue:
          type: object
          description: >-
            The deviating dimension value applied on credit rows. Null when
            `deviateOnCreditRow` is false or not set.
          nullable: true
          required:
            - id
            - dimensionDefinitionId
          properties:
            id:
              type: string
              description: Unique identifier of the deviating preset value.
            dimensionDefinitionId:
              type: string
              description: ID of the dimension definition this deviating value belongs to.
            presetListValueId:
              type: string
              description: >-
                ID of the preset list value used as the deviating value. Null
                when the deviating value is a string.
              nullable: true
            presetListValueText:
              type: string
              description: Text of the preset list value. Null when not applicable.
              nullable: true
            presetStringValue:
              type: string
              description: >-
                String value used as the deviating value. Null when the
                deviating value is a list value.
              nullable: true
        dimensionUsage:
          type: string
          description: >-
            Describes how the dimension is used within the system. Null when not
            configured.
          nullable: true
        visible:
          type: boolean
          description: >
            Computed visibility flag. `true` when the dimension is shown to
            users. Determined by `presetLocation` and user override settings.
    400Error:
      type: object
      properties:
        result:
          type: string
        code:
          type: string
        description:
          type: string
    403Error:
      type: object
      properties:
        result:
          type: string
        description:
          type: string
      example:
        result: error
        description: Not allowed
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````