Approval structures

Configure approval structures for an organization through the Findity Admin API — controlling how expense reports are routed to the correct approvers based on departments, dimensions, or a combination of both.

Key Concepts

An approval structure defines the rules for who approves expense reports within an organization. Findity supports two approval models that can be used independently or combined:

• Department-based approval — Approvers are assigned to departments in the organization structure. When a user submits an expense report, it is routed to the approver of the user's department.
• Dimension-based approval — Approvers are assigned to specific dimension values (e.g., a cost center or project). When a user selects a dimension value on an expense, the report is routed to the approver of that value.

Each approver assignment has the following properties:

Approval Steps

Findity supports up to 3 approval steps per structure. Each step is a level in the approval chain:

When an expense report is submitted, it passes through each step in order. If an approver's amountLimit is exceeded, the report moves to the next step automatically.

⚠️

Approval must be activated in the admin web client (Marketplace) before it can be configured via the API. The API manages approver assignments but does not enable or disable approval itself.

API Endpoints

Approval structures are managed through two sets of endpoints depending on the approval model:

Department-Based Approval

Approvers are configured as part of the organization structure. All endpoints use the Admin API base URL:

https://expense.findity.com/api/admin

Dimension-Based Approval

Approvers are assigned to specific dimension values:

Required Headers

Include these headers with every request:

Step 1 — Choose an Approval Model

Decide which approval model fits your organization:

📘

When combining department and dimension approval, the priority order determines where Findity looks first for an approver. Configure this in the admin web client by ordering the approval structure boxes — the box on top is checked first.

Step 2 — Set Up Department-Based Approval

Assign approvers to departments by updating the organization structure. Each department in the tree has an approvers array.

PUT /organizations/externalid/{externalId}/organizationalunits/

Approver Object Properties

Example: Assign Approvers to a Department

This example updates a department with two approval steps — a manager who can approve up to 5000, and a director with no limit:

{
  "id": "dept-sales-001",
  "name": "Sales",
  "description": "Sales department",
  "approvers": [
    {
      "personId": "8a5c9c38923312df019233426f7d04dd",
      "sortOrder": 0,
      "amountLimit": 5000
    },
    {
      "personId": "9b6d0d49034423ef0203344370e815ee",
      "sortOrder": 1,
      "amountLimit": null
    }
  ],
  "subUnits": []
}

When a user in the Sales department submits an expense report:

1. If the total is 5000 or less, the manager (sortOrder: 0) approves it
2. If the total exceeds 5000, the report moves to the director (sortOrder: 1) after the manager approves

Step 3 — Set Up Dimension-Based Approval

Assign approvers to specific dimension values. This requires a dimension with controlType set to LIST_SEARCHABLE and values already populated.

PUT /organizations/externalid/{externalId}/customdimensions/{dimensionId}/approvers/

Example: Assign Approvers to a Cost Center Value

[
  {
    "dimensionValueId": "CC-100",
    "approverExternalId": "EMP-MGR-001",
    "sortOrder": 0,
    "amountLimit": null
  },
  {
    "dimensionValueId": "CC-200",
    "approverExternalId": "EMP-MGR-002",
    "sortOrder": 0,
    "amountLimit": 10000
  },
  {
    "dimensionValueId": "CC-200",
    "approverExternalId": "EMP-DIR-001",
    "sortOrder": 1,
    "amountLimit": null
  }
]

In this example:

• Expenses tagged with cost center CC-100 are approved by EMP-MGR-001 with no amount limit
• Expenses tagged with cost center CC-200 go through two approval steps: EMP-MGR-002 up to 10,000, then EMP-DIR-001 for any amount

Step 4 — Retrieve the Current Approval Configuration

Get Department Approvers

Retrieve the full organization structure, which includes the approvers array on each department:

GET /organizations/externalid/{externalId}/organizationalunits/

Get Dimension Approvers

Retrieve approvers assigned to a specific dimension's values:

GET /organizations/externalid/{externalId}/customdimensions/{dimensionId}/approvers/

Default Approver

If Findity cannot determine the correct approver — for example, a department's approver has been removed, or a user selects a dimension value with no approver assigned — the expense report is routed to the default approver.

Configure the default approver in the admin web client under Approval settings. This acts as a safety net to prevent expense reports from getting stuck in the approval queue.

Temporary Approvers

Temporary approvers handle vacations and time off. When an approver is unavailable, a temporary replacement can be appointed to receive expense reports in their place.

There are three settings for temporary approver configuration:

Configure this setting in the admin web client under Approval settings.

📘

No extra authorization is required for a user to act as an approver. Any user in the organization can be assigned as an approver — they gain the ability to approve and reject reports but receive no additional administrative permissions.

Common Integration Patterns