Users

Retrieve and manage the authenticated user's profile, preferences, settings, and account details — the starting point for any Expense API integration.

Overview

The Expense API user endpoints operate through the /me context, meaning all operations apply to the currently authenticated user. After authenticating with a user-scoped token (via the authorization_code grant), the /me endpoint is your first call — it returns the user's identity, preferences, and capabilities.

The user context is essential because most Expense API endpoints (expenses, reports, approvals) are scoped to the authenticated user's permissions and organization memberships.

Key concepts

Get current user

Retrieve the authenticated user's profile. This is typically the first call after obtaining a user-scoped access token.

GET /v1/expense/me

Query parameters

Example request

curl -X GET "https://stage-api.findity.com/api/v1/expense/me?include=preferences,meta.capabilities" \
  -H "Authorization: Bearer {access_token}"

Example response

{
  "id": "370e10197a2740dea1f39d21bc9e4a8c",
  "email": "[email protected]",
  "firstName": "Emma",
  "lastName": "Expense",
  "mobilePhone": "+4670123456789",
  "defaultCurrency": "USD",
  "language": "en_US",
  "IBAN": "US2138890474392778363181",
  "BIC": "ABCDEF123",
  "formattingRegion": "sv_SE",
  "address": {
    "id": "2ee7643987df40b38537b32ccda585d9",
    "street1": "132, My Street",
    "postalCode": "12401",
    "city": "New York",
    "countryCode": "US"
  },
  "meta": {
    "capabilities": {
      "canImpersonate": false,
      "canViewAdmin": false
    }
  }
}

Update current user

Update the authenticated user's profile information.

PUT /v1/expense/me

Example request

curl -X PUT "https://stage-api.findity.com/api/v1/expense/me" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Emma",
    "lastName": "Expense",
    "defaultCurrency": "SEK",
    "language": "sv_SE",
    "IBAN": "SE3550000000054910000003",
    "BIC": "ESSESESS",
    "address": {
      "street1": "Sveavägen 10",
      "postalCode": "111 57",
      "city": "Stockholm",
      "countryCode": "SE"
    },
    "formattingRegion": "sv_SE"
  }'

Updatable fields

Action parameter

The PUT /me endpoint also supports an action query parameter instead of a request body:

PUT /v1/expense/me?action=enableSupportAccess

User settings (fields format)

User settings can also be fetched and updated using the fields format — the same dynamic form system used for expenses. This is useful when building a full settings UI.

Fetch settings

GET /v1/expense/me/settings/fields

Returns a fields structure with grouped settings:

Update settings

PUT /v1/expense/me?format=fields

Send the full fields structure back with updated values. Fields with requiresUpdate: true trigger server-side recalculation — follow the same update loop pattern described in the Fields system guide.

Counters

Retrieve badge counts across all organizations the user belongs to. Use this to show notification badges in your UI.

GET /v1/expense/me/counters

Example response

{
  "meta": { "count": 2, "total": 2 },
  "data": [
    {
      "organizationId": "8ab28c4e6f858814016f8a9bd6b20054",
      "expenses": 19,
      "approvals": 0,
      "rejections": 0,
      "notifications": 3,
      "transactions": 0,
      "inbox": 0
    },
    {
      "organizationId": "8ab28c4f6fd37d39016fd6fee0470003",
      "expenses": 10,
      "approvals": 11,
      "rejections": 0,
      "notifications": 0,
      "transactions": 0,
      "inbox": 0
    }
  ]
}

Counter fields

Profile image

Manage the user's profile picture.

When uploading, set the Content-Type header to the image format (e.g., image/jpeg, image/png). The request body should be the binary image data.

Email and phone management

Email and phone number changes require a two-step verification process to prevent unauthorized changes.

Change email

1. Request a verification code:

curl -X POST "https://stage-api.findity.com/api/v1/expense/me/email?action=change" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]" }'

2. Verify with the code:

curl -X POST "https://stage-api.findity.com/api/v1/expense/me/email?action=verify" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ "verificationCode": "123456" }'

Change phone number

Follows the same two-step pattern using /v1/expense/me/phone:

1. POST /me/phone?action=change with { "phoneNumber": "+46701234567" }
2. POST /me/phone?action=verify with { "verificationCode": "123456" }

To remove a phone number entirely: DELETE /v1/expense/me/phone

📱

Phone numbers must be in international format with a plus-code prefix (e.g., +46701234567).

Change password

POST /v1/expense/me/password

Example request

{
  "oldPassword": "currentPassword123!",
  "newPassword": "newSecurePassword456!"
}

A successful response returns new access and refresh tokens, since the password change invalidates the previous session:

{
  "expiresIn": 3600,
  "accessToken": "eae3a3a225368f247b419e...",
  "refreshToken": "59fec24de9f49918f50a31..."
}

🔒

Passwords must be at least eight characters long with at least one number, one uppercase letter, and one lowercase letter.

🔄

After a successful password change, immediately replace your stored access and refresh tokens with the new ones returned in the response. The old tokens are invalidated and will no longer work.

Extra recipients

Extra recipients are additional email addresses that receive expense-related notifications alongside the user's primary email.

Each extra recipient has a status of CONFIRMED or NOT_CONFIRMED — they must complete email verification before receiving notifications.

Impersonation

Users with impersonation privileges can search for and act as other users. This is used for admin tools, support scenarios, and delegated expense management.

Search impersonation targets

GET /v1/expense/impersonation/users/search

Example response

{
  "meta": { "total": 2, "count": 2 },
  "data": [
    {
      "personId": "a61fa8a24d9d49f7b75d1874257e044a",
      "firstName": "Emma",
      "lastName": "Expense",
      "email": "[email protected]",
      "impersonatorType": "PERSON",
      "profilePictureUrl": "https://expense.findity.com/api/v1/expense/profileimage/a61fa..."
    }
  ]
}

The impersonatorType indicates the scope of impersonation:

⚠️

Impersonation requires special permissions. Check meta.capabilities.canImpersonate on the /me response before showing impersonation features in your UI.

Integration best practices

Error handling

Common errors when working with user endpoints:

Next steps