Users

Manage users (employees, approvers, administrators, and consultants) within an organization through the Findity Admin API.

Key Concepts

A user represents a person within a Findity organization. Users can create expenses, approve expense reports, administer organization settings, or access bookkeeping data — depending on their assigned role. Key properties of a user include:

Property	Description
`externalSourceId`	A unique identifier from your external system (e.g., HR or ERP), used to address the user across API calls
`firstName`	First name of the user
`lastName`	Last name of the user
`email`	Email address used for login and notifications
`personnelNumber`	Employee number from your HR system
`organizationalUnitId`	The department ID the user belongs to (from the organization structure)
`role`	The user’s role within the organization (see User Types below)
`locale`	Language/locale preference (e.g., `sv_SE`, `en_GB`)
`approverIds`	Array of `personId` values for the user’s designated approvers

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

API Endpoints

All endpoints are available under the Admin API base URL:

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

The following operations are available:

Operation	Method	Endpoint
List users	`GET`	`/organizations/externalid/{externalId}/users/`
Get user by external ID	`GET`	`/organizations/externalid/{externalId}/users/externalid/{userExternalId}/`
Create or update users	`PUT`	`/organizations/externalid/{externalId}/users/`
Delete user	`DELETE`	`/organizations/externalid/{externalId}/users/externalid/{userExternalId}/`

Required Headers

Include these headers with every request:

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

Step 1 — List Users

Retrieve all users belonging to an organization.

bash

GET /organizations/externalid/{externalId}/users/

This returns an array of user objects. Use this to discover existing users before creating new ones or to verify sync state.

Step 2 — Create or Update Users

Create new users or update existing ones by sending a PUT request. The endpoint performs an upsert based on externalSourceId — if a user with that ID exists, it is updated; otherwise, a new user is created.

bash

PUT /organizations/externalid/{externalId}/users/

The request body accepts an array of user objects, allowing you to sync multiple users in a single call.

Query Parameters

Parameter	Type	Default	Description
`sendInvitationMail`	boolean	`true`	Whether Findity should send an invitation email when creating a new user

If you create users without sending invitation emails immediately, set sendInvitationEmail=false on the request.

bash

PUT /organizations/externalid/{externalId}/users/?sendInvitationMail=false

Request Body Properties

Property	Type	Required	Description
`externalSourceId`	string	Yes	Unique external identifier for the user
`firstName`	string	Yes	First name
`lastName`	string	Yes	Last name
`email`	string	Yes	Email address (used for login)
`personnelNumber`	string	No	Employee number from your HR system
`organizationalUnitId`	string	No	Department ID to assign the user to (from organization structure)
`role`	string	No	User role (see User Types)
`locale`	string	No	Language/locale (e.g., `sv_SE`, `en_GB`)
`approverIds`	array	No	Array of `personId` values for designated approvers
`phone`	string	No	Phone number
`address`	object	No	User’s postal address
`dimensionPresets`	array	No	Preset dimension values for the user (used when a dimension’s `presetLocation` is `EMPLOYEE`)

Example: Create New Users

[
  {
    "externalSourceId": "EMP-001",
    "firstName": "Anna",
    "lastName": "Svensson",
    "email": "anna.svensson@example.com",
    "personnelNumber": "10001",
    "organizationalUnitId": "dept-hq-001",
    "locale": "sv_SE"
  },
  {
    "firstName": "Erik",
    "lastName": "Johansson",
    "email": "erik.johansson@example.com",
    "personnelNumber": "10002",
    "organizationalUnitId": "dept-rd-001",
    "locale": "sv_SE"
  }
]

Example: Update an Existing User

When updating, include the externalSourceId to match the existing user. Include only the fields you want to change.

[
  {
    "externalSourceId": "EMP-001",
    "organizationalUnitId": "dept-finance-001",
    "email": "anna.svensson-new@example.com"
  }
]

Step 3 — Get a User

Retrieve a single user by their external ID.

bash

GET /organizations/externalid/{externalId}/users/externalid/{userExternalId}/

Step 4 — Delete a User

Remove a user from an organization by their external ID.

bash

DELETE /organizations/externalid/{externalId}/users/externalid/{userExternalId}/

Deleting a user removes their access to the organization. Existing expense reports created by the user are retained, but the user can no longer log in or create new expenses.

User Types

Findity supports several user roles, each with different permissions:

Role	Description
Employee	Standard user who can create and manage their own expenses, mileage, and per diem claims
Approver	Can approve or reject expense reports submitted by other users. Assigned via department approvers or dimension approvers
Administrator	Full access to organization settings, user management, categories, dimensions, and reporting
Partner Admin	Manages all organizations within a partner. Can access and configure multiple organizations
Consultant	External user with access for accounting purposes. Cannot create private expenses but can access bookkeeping data across multiple organizations

Department Assignment

Assign a user to a department by setting the organizationalUnitId field to the department’s id from the organization structure.

Call GET /organizations/externalid/{externalId}/organizationalunits/ to retrieve the department tree
Find the target department’s id in the response
Set organizationalUnitId to that id when creating or updating the user

Department assignment determines:

Which approver reviews the user’s expense reports (when approval is based on organization structure)
Which preset dimension values auto-fill from the DEPARTMENT preset location
How the user appears in organizational reporting

If you change a user’s department, their future expense reports use the new department’s approval chain. Existing submitted reports continue through the approval chain that was active at the time of submission.

Dimension Presets on Users

When a dimension has presetLocation set to EMPLOYEE, the preset value is pulled from the user’s dimensionPresets array. This auto-fills dimension fields when the user creates an expense, reducing manual data entry. Each preset entry links a dimension’s externalSourceId to a specific dimension value:

{
  "dimensionPresets": [
    {
      "dimensionExternalSourceId": "COST_CENTER",
      "dimensionValueId": "CC-100"
    },
    {
      "dimensionExternalSourceId": "PROJECT",
      "dimensionValueId": "PROJ-2024-001"
    }
  ]
}

Whether the user can override these values depends on the dimension’s userOverridable setting.

Common Integration Patterns

Onboarding Employees from HR

When onboarding new employees from your HR system:

Call GET /organizations/externalid/{externalId}/organizationalunits/ to retrieve the department structure and find the target organizationalUnitId
Call PUT /organizations/externalid/{externalId}/users/ with an array of new user objects, each containing externalSourceId, firstName, lastName, email, and organizationalUnitId
Set dimensionPresets for each user if your dimensions use EMPLOYEE preset location (e.g., cost center per employee)
After creation, the users can log in and start creating expenses

Nightly HR Sync

To keep user data in sync with your HR system on a schedule:

Export the current employee list from your HR system
Call PUT /organizations/externalid/{externalId}/users/ with the full list — the endpoint upserts based on externalSourceId, creating new users and updating existing ones
Update organizationalUnitId for any department transfers

Multi-Organization Consultants

To grant a consultant access to multiple organizations:

Create the consultant user in each organization separately, using the same email across all organizations
Set the appropriate role for consultant access — consultants can view bookkeeping data but cannot create private expenses
The consultant logs in once and can switch between organizations in the Findity interface

Setting Up Approval Chains

Configure expense report approval using dimensions for maximum flexibility. Department-based approval is being phased out in favor of dimension-based approval.

Activate approval in the admin web client
Create a dimension for approval routing (e.g., DEPARTMENT or COST_CENTER) — see Dimensions
Add approvers to the relevant dimension values, each with a personId referencing the approver’s user
Set dimensionPresets on each user to assign them to the correct dimension value — their expense reports are automatically routed to the approvers configured on that value
For multi-step approval, set sortOrder on each approver entry and optionally configure amountLimit thresholds

Home

MCP Server

API Basics

Guides

Key Concepts

API Endpoints

Required Headers

Step 1 — List Users

Step 2 — Create or Update Users

Query Parameters

Request Body Properties

Example: Create New Users

Example: Update an Existing User

Step 3 — Get a User

Step 4 — Delete a User

User Types

Department Assignment

Dimension Presets on Users

Common Integration Patterns

Next step

​Key Concepts

​API Endpoints

​Required Headers

​Step 1 — List Users

​Step 2 — Create or Update Users

​Query Parameters

​Request Body Properties

​Example: Create New Users

​Example: Update an Existing User

​Step 3 — Get a User

​Step 4 — Delete a User

​User Types

​Department Assignment

​Dimension Presets on Users

​Common Integration Patterns

​Next step

Key Concepts

API Endpoints

Required Headers

Step 1 — List Users

Step 2 — Create or Update Users

Query Parameters

Request Body Properties

Example: Create New Users

Example: Update an Existing User

Step 3 — Get a User

Step 4 — Delete a User

User Types

Department Assignment

Dimension Presets on Users

Common Integration Patterns

Next step