> ## Documentation Index
> Fetch the complete documentation index at: https://developer.findity.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/docs/departments-new)) |
| `role` | The user's role within the organization (see [User Types](#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 bash theme={"system"}
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 bash theme={"system"}
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 bash theme={"system"}
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](/docs/departments-new)) |
| `role` | string | No | User role (see [User Types](#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
```json theme={"system"}
[
{
"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.
```json theme={"system"}
[
{
"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 bash theme={"system"}
GET /organizations/externalid/{externalId}/users/externalid/{userExternalId}/
```
## Step 4 — Delete a User
Remove a user from an organization by their external ID.
```bash bash theme={"system"}
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](/docs/departments-new).
1. Call `GET /organizations/externalid/{externalId}/organizationalunits/` to retrieve the department tree
2. Find the target department's `id` in the response
3. 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](/docs/dimensions-new) 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:
```json theme={"system"}
{
"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
When onboarding new employees from your HR system:
1. Call `GET /organizations/externalid/{externalId}/organizationalunits/` to retrieve the department structure and find the target `organizationalUnitId`
2. Call `PUT /organizations/externalid/{externalId}/users/` with an array of new user objects, each containing `externalSourceId`, `firstName`, `lastName`, `email`, and `organizationalUnitId`
3. Set `dimensionPresets` for each user if your dimensions use `EMPLOYEE` preset location (e.g., cost center per employee)
4. After creation, the users can log in and start creating expenses
To keep user data in sync with your HR system on a schedule:
1. Export the current employee list from your HR system
2. Call `PUT /organizations/externalid/{externalId}/users/` with the full list — the endpoint upserts based on `externalSourceId`, creating new users and updating existing ones
3. Update `organizationalUnitId` for any department transfers
To grant a consultant access to multiple organizations:
1. Create the consultant user in each organization separately, using the same `email` across all organizations
2. Set the appropriate `role` for consultant access — consultants can view bookkeeping data but cannot create private expenses
3. The consultant logs in once and can switch between organizations in the Findity interface
Configure expense report approval using [dimensions](/docs/dimensions-new) for maximum flexibility. Department-based approval is being phased out in favor of dimension-based approval.
1. Activate approval in the admin web client
2. Create a dimension for approval routing (e.g., `DEPARTMENT` or `COST_CENTER`) — see [Dimensions](/docs/dimensions-new)
3. Add approvers to the relevant dimension values, each with a `personId` referencing the approver's user
4. 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
5. For multi-step approval, set `sortOrder` on each approver entry and optionally configure `amountLimit` thresholds
## Next step
Define approval workflows and routing rules.