Approval on dimensions new

Configure an approval structure on an existing dimension so that expense reports are automatically routed to the correct approver based on dimension values, like cost centers or projects.

API endpoints used in this guide

Operation	Method	Endpoint
List users	`GET`	`/organizations/externalid/{externalId}/users/`
Create or update approvers	`PUT`	`/organizations/externalid/{externalId}/customdimensions/{id}/list/approvers/`

📘
This guide uses externalSourceId to address organizations, users, and dimensions. Make sure your external system IDs are set on all resources before proceeding.

⚠️
Always use the externalId endpoints (/organizations/externalid/{externalId}/). The internalId variants are legacy and will be phased out.

Prerequisites

An organization with externalSourceId configured
A dimension with list values — see Dimensions
Users with dimension presets assigned

Required headers

Include these headers in every request:

Header	Value
`Content-Type`	`application/json`
`X-Findity-ApiVersion`	`3`
`Authorization`	`Bearer {access_token}`

Step 1: Activate approval

🚧
At this time, you need to activate approval in the Admin UI before configuring approvers via the API.

Open the Admin UI for your organization.
Navigate to the approval settings.
Enable approval on the dimension you want to use for routing (e.g., "Costcenter").

Step 2: Assign an approver to a dimension value

Identify the approver's externalSourceId. If needed, list all users in the organization with the List users endpoint and find the externalSourceId on the person object.

Assign the approver to a dimension value using the Create or update approvers endpoint. The example below sets a manager as an approver on cost center 100.

Property	Purpose
`approverExternalId`	The `externalSourceId` of the person to assign as approver.
`dimensionValueId`	The dimension value to attach the approver to (e.g., `100`).
`sortOrder`	Determines approval order. `0` makes this person the first approver.
`amountLimit`	Optional. Maximum amount this approver can approve before escalation.

✅
Expense reports from users with cost center 100 preset are now automatically routed to the assigned approver.

Next steps

Configure multi-step approval chains by adding more approvers with incremental sortOrder values
Set amountLimit thresholds to create escalation-based approval workflows
Learn more about dimension configuration in the Dimensions guide