Dimensions

What are dimensions?

Dimensions are custom fields attached to expenses or expense reports that map to your organization's accounting structure. You define the dimensions that match your business — there are no fixed categories.

Because dimensions are fully configurable, they also enable flexible approval structures. Assign approvers to specific dimension values — for example, route all "Marketing" cost center expenses to a marketing manager — and build multi-step approval chains that mirror your organization's policies.

Each dimension has a definition (its name, type, and behavior) and optionally a set of list values that users can select from.

API endpoints

All dimension endpoints use the organization's externalId as the base path:

/organizations/externalid/{externalId}/customdimensions/

Step 1: Create or update dimension definitions

Send a PUT request with an array of dimension definitions. This is an upsert operation — existing dimensions with the same externalSourceId are updated, and new ones are created.

Definition properties

Example request

curl -X PUT \
  "https://api.findity.com/api/v1/admin/organizations/externalid/org-acme-123/customdimensions/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "externalSourceId": "dim-costcenter",
      "description": "Cost Center",
      "level": "EXPENSE",
      "controlType": "LIST_SEARCHABLE",
      "presetLocation": "DEPARTMENT",
      "userOverridable": true,
      "visibleIfNoPreset": true
    },
    {
      "externalSourceId": "dim-project",
      "description": "Project",
      "level": "EXPENSE",
      "controlType": "LIST_SEARCHABLE",
      "presetLocation": "NONE"
    },
    {
      "externalSourceId": "dim-invoice-ref",
      "description": "Invoice Reference",
      "level": "EXPENSE_REPORT",
      "controlType": "TEXT",
      "presetLocation": "NONE"
    }
  ]'

This creates three dimensions:

• Cost Center — a searchable list on each expense, auto-filled from the user's department but overridable
• Project — a searchable list on each expense with no preset
• Invoice Reference — a free-text field on the expense report header

Step 2: Populate list values

Dimensions with controlType: LIST_SEARCHABLE need list values for users to select from. Send a PUT request with the values array.

Query parameters

List value properties

Example request

curl -X PUT \
  "https://api.findity.com/api/v1/admin/organizations/externalid/org-acme-123/customdimensions/dim-project/list/?clearBeforeUpdate=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "id": "proj-001",
      "value": "Website Redesign",
      "sortOrder": 1,
      "startDate": "2025-01-01",
      "endDate": "2025-12-31"
    },
    {
      "id": "proj-002",
      "value": "Mobile App v2",
      "sortOrder": 2,
      "startDate": "2025-03-01"
    },
    {
      "id": "proj-003",
      "value": "Internal Tools",
      "sortOrder": 3
    }
  ]'

In this example:

• Website Redesign is available only during 2025
• Mobile App v2 becomes available from March 2025 onward (no end date)
• Internal Tools has no date restrictions
• clearBeforeUpdate=true replaces all existing project values with these three

⚠️

Setting clearBeforeUpdate=true removes all existing values before inserting. Make sure your request includes the complete set of values you want to keep.

Step 3: Manage approvers (optional)

Assign approvers to specific dimension values to automatically route expense approvals based on the selected dimension value.

Example request

curl -X PUT \
  "https://api.findity.com/api/v1/admin/organizations/externalid/org-acme-123/customdimensions/dim-project/list/approvers/" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "dimensionValueId": "proj-001",
      "approverExternalId": "emp-jane-smith"
    },
    {
      "dimensionValueId": "proj-002",
      "approverExternalId": "emp-john-doe"
    }
  ]'

This assigns Jane Smith as the approver for "Website Redesign" expenses and John Doe for "Mobile App v2" expenses.

Understanding presets

Presets auto-fill dimension values based on existing data, reducing manual input for users. The presetLocation, userOverridable, and visibleIfNoPreset properties work together:

When a preset is configured:

• userOverridable: true — The dimension is auto-filled but the user can change it. Use this when presets are a helpful default but exceptions are common.
• userOverridable: false — The dimension is auto-filled and locked. Use this to enforce accounting rules.
• visibleIfNoPreset: true — If no preset value exists for the user/department/category, the dimension still appears and the user enters a value manually.
• visibleIfNoPreset: false — If no preset value exists, the dimension is hidden entirely.

Common integration patterns

Next step