Skip to navigation
API ReferenceDimensions

Create a single new dimension

Creates a new dimension with the provided details. All fields in the request body are required. This endpoint does not upsert: if a dimension with the same reference_id and erp_type already exists for the company, the request is rejected with a 400 error instead of updating the existing record. To update an existing dimension, use POST /dimensions/bulk, which upserts by reference_id + erp_type.

Authentication

AuthorizationBearer
OAuth2 authentication flows. Auth server URLs will vary by environment

Headers

X-Api-KeystringRequired
API key for authentication
X-API-VersionstringOptional

API version to use (optional, defaults to latest). Supported values: 1.0.0, 1.1.0.

Idempotency-KeystringOptionalformat: "^[A-Za-z0-9._\-+=/]{1,128}$"<=128 characters

Client-generated unique key (UUID/ULID recommended). JSON requests: the first 2xx response is cached for 24h and replayed on a same-key retry with a matching body; a different body returns 422. Non-JSON requests (e.g. file uploads): the key is single-use — any same-key retry returns 422 regardless of body. See Idempotency for full details.

Request

This endpoint expects an object.
ottimate_company_idintegerRequired
The Ottimate company ID this dimension belongs to
erp_typestringRequired

The dimension category label as displayed in the client’s ERP system (e.g., ‘Account’, ‘GLACCOUNT’, ‘Department’). This is client-specific.

ottimate_typeenumRequired
Ottimate's standardized dimension type code for consistent categorization.
namestringRequired
Display name of the dimension
codestringRequired
The GL code or short identifier for this dimension in the client's ERP system
reference_idstringRequired

A unique reference identifier that tracks this dimension across all client systems (ERP, inventory management, Ottimate)

erp_dimension_idstringRequired
The identifier assigned to this dimension by the client's ERP software

Response

Successfully created. The created dimension is returned nested under a dimension key, matching the shape of the GET /dimensions/{id} response. There is no timestamp field (e.g. created_date) in the response.

versionstringOptional
dimensionobjectOptional

Errors

400
Bad Request Error
403
Forbidden Error
422
Unprocessable Entity Error