Users

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:

⚠️

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:

Required Headers

Include these headers with every request:

Step 1 — List Users

Retrieve all users belonging to an organization.

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.

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

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

Request Body Properties

Example: Create New Users

[
  {
    "externalSourceId": "EMP-001",
    "firstName": "Anna",
    "lastName": "Svensson",
    "email": "[email protected]",
    "personnelNumber": "10001",
    "organizationalUnitId": "dept-hq-001",
    "locale": "sv_SE",
    "active": true
  },
  {
    "externalSourceId": "EMP-002",
    "firstName": "Erik",
    "lastName": "Johansson",
    "email": "[email protected]",
    "personnelNumber": "10002",
    "organizationalUnitId": "dept-rd-001",
    "locale": "sv_SE",
    "active": true
  }
]

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": "[email protected]",
    "active": true
  }
]

Step 3 — Get a User

Retrieve a single user by their external ID.

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

Step 4 — Delete a User

Remove a user from an organization by their external ID.

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:

Department Assignment

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

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 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

Next step