Dimensions

Overview

In accounting systems, financial transactions must be properly categorized for reporting and compliance. Transactions are assigned to GL accounts, departments, locations, projects, and other organizational segments based on a company’s accounting rules.

Ottimate represents these transaction classifications through dimensions. Each dimension links an Ottimate record to a corresponding entity in the client’s ERP/accounting system.

Key Characteristics:

• Dimensions are company-specific - each company maintains its own set of dimensions
• Dimensions must be synced from your ERP before invoices can be properly coded
• The erp_dimension_id links Ottimate dimensions to your accounting system
• Dimensions can be applied at both invoice header and line item level

Dimension Fields

Response Fields

Creation Fields

Supported Dimension Types

The following dimension types are supported. The table shows equivalent entities across common ERP systems.

GL Account (account)

Classifies how a transaction will be recorded in the general ledger.

Example:

1
{
2
  "id": "dim_VOH21Up3M7HV",
3
  "name": "Food Cost",
4
  "type": "Account",
5
  "dimension_type": "account",
6
  "erp_dimension_id": "5000",
7
  "ottimate_company_id": 123
8
}

Location (location)

Represents geographic locations like offices, facilities, or warehouses.

Department (department)

Represents internal business units or functions.

Project (project)

Tracks transactions related to a specific initiative, job, or capital effort.

Task (task)

Represents specific tasks within a project.

Cost Type (cost_type)

Categorizes different types of costs within projects.

Item (item)

Represents goods and services purchased from vendors.

Sync Patterns

Ottimate-Hosted ERP Integrations

When you use an Ottimate-hosted integration (e.g., QuickBooks, NetSuite, Sage), Ottimate automatically syncs dimensions from your ERP:

• Initial sync happens during onboarding
• Ongoing sync keeps dimensions updated automatically
• No API calls needed - dimension management is handled by the integration

In this scenario, you primarily use the Dimensions API to read dimension data for reference or validation.

Custom ERP Integrations

If you’re building a custom integration with an unsupported ERP, you’re responsible for syncing dimensions:

1. Extract dimension data from your ERP (chart of accounts, departments, etc.)
2. Transform to Ottimate’s dimension format
3. Load via the Dimensions API (POST /dimensions or POST /dimensions/bulk-create/)
4. Maintain ongoing sync as dimensions are added/updated in your ERP

API Operations

List Dimensions

Retrieve all dimensions for a company, optionally filtered by type:

$
GET /v1/dimensions?ottimate_company_id=123&type=Account

Response:

1
{
2
  "version": "1.0.0",
3
  "count": 100,
4
  "page": 1,
5
  "limit": 20,
6
  "dimensions": [
7
    {
8
      "id": "dim_VOH21Up3M7HV",
9
      "name": "Food Cost",
10
      "type": "Account",
11
      "erp_dimension_id": "5000",
12
      "dimension_type": "account",
13
      "ottimate_company_id": 123
14
    },
15
    {
16
      "id": "dim_XKL45Qp8N2RT",
17
      "name": "Beverage Cost",
18
      "type": "Account",
19
      "erp_dimension_id": "5100",
20
      "dimension_type": "account",
21
      "ottimate_company_id": 123
22
    }
23
  ]
24
}

Get Single Dimension

Retrieve a specific dimension by ID:

$
GET /v1/dimensions/dim_VOH21Up3M7HV

Response:

1
{
2
  "version": "1.0.0",
3
  "dimension": {
4
    "id": "dim_VOH21Up3M7HV",
5
    "name": "Food Cost",
6
    "type": "Account",
7
    "erp_dimension_id": "5000",
8
    "dimension_type": "account",
9
    "ottimate_company_id": 123
10
  }
11
}

Create Single Dimension

Create a new dimension:

$
POST /v1/dimensions
$
Content-Type: application/json
$
$
{
>
  "ottimate_company_id": 123,
>
  "type": "Department",
>
  "dimension_type_code": "department",
>
  "name": "Marketing Department",
>
  "code": "MKT",
>
  "unique_key": "dept-mkt-001",
>
  "erp_dimension_id": "DEPT-MKT-001"
>
}

Response (201 Created):

1
{
2
  "version": "1.0.0",
3
  "id": "dim_ABC12345XYZ",
4
  "name": "Marketing Department",
5
  "type": "Department",
6
  "erp_dimension_id": "DEPT-MKT-001",
7
  "dimension_type": "department",
8
  "ottimate_company_id": 123,
9
  "created_date": "2024-12-05T10:30:00Z"
10
}

Bulk Create/Update Dimensions

Create or update multiple dimensions in a single request. This endpoint uses upsert behavior - existing dimensions (matched by unique_key) are updated, new dimensions are created.

$
POST /v1/dimensions/bulk-create/
$
Content-Type: application/json
$
$
{
>
  "ottimate_company_id": 123,
>
  "dimensions": [
>
    {
>
      "type": "Department",
>
      "dimension_type_code": "department",
>
      "name": "Operations Department",
>
      "code": "OPS",
>
      "unique_key": "dept-ops-001",
>
      "erp_dimension_id": "DEPT-OPS-001"
>
    },
>
    {
>
      "type": "Department",
>
      "dimension_type_code": "department",
>
      "name": "Finance Department",
>
      "code": "FIN",
>
      "unique_key": "dept-fin-001",
>
      "erp_dimension_id": "DEPT-FIN-001"
>
    }
>
  ]
>
}

Response (201 Created):

1
{
2
  "version": "1.0.0",
3
  "success_count": 3,
4
  "created_count": 2,
5
  "updated_count": 1,
6
  "error_count": 0,
7
  "created": [
8
    {
9
      "id": "dim_DEF67890ABC",
10
      "name": "Operations Department"
11
    },
12
    {
13
      "id": "dim_GHI11223DEF",
14
      "name": "Finance Department"
15
    }
16
  ],
17
  "updated": [
18
    {
19
      "id": "dim_VOH21Up3M7HV",
20
      "name": "Food Cost (Updated)"
21
    }
22
  ],
23
  "errors": []
24
}

Partial Failure Response (207 Multi-Status):

1
{
2
  "version": "1.0.0",
3
  "success_count": 1,
4
  "created_count": 1,
5
  "updated_count": 0,
6
  "error_count": 1,
7
  "created": [
8
    {
9
      "id": "dim_JKL44556GHI",
10
      "name": "HR Department"
11
    }
12
  ],
13
  "updated": [],
14
  "errors": [
15
    {
16
      "index": 1,
17
      "unique_key": "invalid-dim",
18
      "error": "dimension_type_code is required",
19
      "type": "validation_error"
20
    }
21
  ]
22
}

Using Dimensions in Invoices

Dimensions are applied to invoices and line items to categorize transactions for proper GL coding.

Invoice Header Dimensions: Used for header-level coding that applies to the entire invoice (e.g., department, location).

Line Item Dimensions: Used for item-level coding when different line items should be coded to different accounts.

1
{
2
  "ottimate_company_id": 123,
3
  "ottimate_location_id": 456,
4
  "ottimate_vendor_id": 789,
5
  "invoice_number": "INV-001",
6
  "dimensions": {
7
    "Department": "DEPT-MKT-001",
8
    "Location": "LOC-001"
9
  },
10
  "line_items": [
11
    {
12
      "description": "Office Supplies",
13
      "amount": 150.00,
14
      "dimensions": {
15
        "Account": "5000"
16
      }
17
    }
18
  ]
19
}

Best Practices

Troubleshooting

”Dimension not found” when coding invoice

• Verify the dimension exists: GET /dimensions?ottimate_company_id=123&type=Account
• Check you’re using the correct erp_dimension_id value
• Ensure the dimension belongs to the same company as the invoice

Invoice export fails with dimension error

• Verify the erp_dimension_id matches exactly what’s in your ERP
• Check that all required dimension types are populated on the invoice

Bulk create shows errors

• Check the errors array in the response for specific validation failures
• Common issues: missing dimension_type_code, missing unique_key, invalid type

Dimensions not syncing from ERP

• For Ottimate-hosted integrations, check sync status in the dashboard
• For custom integrations, verify your API calls are succeeding