---
title: "Create or update multiple dimensions"
method: POST
path: "/dimensions/bulk"
tags: ["dimensions"]
---

# Create or update multiple dimensions

`POST /dimensions/bulk`

Allows for the creation or updating of multiple dimensions in a single request. The request body should contain a `ottimate_company_id` and an array of `dimensions`. Maximum 100 dimensions per request. Unlike `POST /dimensions` (single-create), this endpoint upserts: existing dimensions (matched by `reference_id` + `erp_type`) are updated, new dimensions are created. Validation is checked for every item before any writes happen — if any item is missing a required field or has an unresolvable type, the entire request is rejected with `400` and nothing is created or updated, including otherwise-valid items in the same batch.

## Headers

- `Authorization` string, required
- `X-Api-Key` string, required
- `X-API-Version` string
- `Idempotency-Key` string

## Request body

- object
  - `ottimate_company_id` integer, required — The Ottimate company ID these dimensions belong to
  - `dimensions` DimensionsBulkPostRequestBodyContentApplicationJsonSchemaDimensionsItems[], required
    - `erp_type` string, required — The dimension category label in client's ERP system
    - `ottimate_type` 'account' | 'location' | 'department' | 'class' | 'project' | 'customer' | 'entity' | 'item' | 'warehouse' | 'task' | 'cost_type' | 'employee' | 'tax_code' | 'property' | 'company' | 'subsidiary', required — Ottimate's standardized dimension type code
    - `name` string, required — Display name of the dimension
    - `code` string, required — The GL code or short identifier for this dimension
    - `reference_id` string, required — A unique reference identifier that tracks this dimension across all client systems
    - `erp_dimension_id` string, required — The identifier assigned to this dimension by the client's ERP software

## Response `200`

Successfully created and/or updated. Returned whenever at least one item in the batch succeeds — including batches where some items succeeded and others failed at the individual-record level (see `fail_count`/`failures` below); there is no separate 207 status for this case.

- DimensionsPostDimensionsBulkResponse200
  - `version` string
  - `success_count` integer
  - `created_count` integer
  - `updated_count` integer
  - `fail_count` integer
  - `created` DimensionsBulkPostResponsesContentApplicationJsonSchemaCreatedItems[] — Full dimension objects that were newly created (same shape as the single-create response's `dimension` object).
    - `id` string
    - `ottimate_company_id` integer
    - `ottimate_type` string
    - `name` string
    - `code` string
    - `erp_type` string
    - `reference_id` string
    - `erp_dimension_id` string
  - `updated` DimensionsBulkPostResponsesContentApplicationJsonSchemaUpdatedItems[] — Full dimension objects that were updated (same shape as `created`).
    - `id` string
    - `ottimate_company_id` integer
    - `ottimate_type` string
    - `name` string
    - `code` string
    - `erp_type` string
    - `reference_id` string
    - `erp_dimension_id` string
  - `failures` DimensionsBulkPostResponsesContentApplicationJsonSchemaFailuresItems[] — Items that passed request validation but failed while being written (e.g. a record-level conflict). Empty for the all-or-nothing validation failures described under 400 below, since those never reach this response at all.
    - `index` integer
    - `unique_key` string
    - `erp_type` string
    - `error` string

## Other responses

- `400` — Bad Request. Returned for the entire batch if ANY item is missing a required field or has an unresolvable type — validation happens for every item before any dimensions are written, so a single bad item anywhere in the array rejects the whole request, including otherwise-valid items. A batch of one valid item and one item missing `code` returns 400 for the whole request, not a 200/207 with the valid item created.
- `403` — Forbidden - Access denied or insufficient permissions

---

[API](https://skmtc.dev/ottimate/apis/api-reference.md) · [All operations](https://skmtc.dev/ottimate/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ottimate/api-reference/revisions/ba91ff4c6969/schema)