> ## 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. # Update user > Changes a user of the given organization and returns it as the list returns it. Only the properties in the body are changed: a property that is left out keeps its value, and `null` clears an optional property. A user read from the list can be sent back, changed or not; leave out `language` when it is `null`. `email` and `ssn` can't be changed: the email address is the user's login and the identity number identifies the person. They are accepted when they equal the user's current values, otherwise the request is rejected. The read-only `id`, `lastInvitationDate` and `dateCreated` are ignored. The values get the same checks as when a user is created: unknown departments, dimensions, dimension values and languages, invalid bank account numbers, IBAN and BIC values, and an `endDate` in the past are rejected instead of ignored. An `endDate`, `bankAccountNumber`, `IBAN` or `BIC` sent back unchanged isn't checked again; the other values, such as `department` and `customDimensionPresetValues`, are checked even when unchanged. No other user of the organization may have the same `externalSourceId` or `employeeId`. `firstName`, `lastName`, `mobilePhone`, `language`, `bankAccountNumber`, `IBAN` and `BIC` belong to the person behind the user, which every organization employing that person shares. While the person is also a (not deleted) user of another organization, these can't be changed, so one organization can't change another's data or redirect its reimbursements: they are accepted when they equal the current values, otherwise the request is rejected with 400 and code `INVALID_JSON_PROPERTY_VALUE`, and nothing is changed. Bank details count as unchanged when they only differ in formatting, such as spaces or dashes. The properties of the employment itself, such as `employeeId`, `department` and `isAdministrator`, can still be changed. Making a user an administrator also gives them the organization administrator role. A changed department only changes the user's department; reports already sent for approval keep their approvers. Returns 403 when the organization does not exist or the authenticated user is not an administrator of it, so a caller cannot tell an organization they lack access to from a missing one. Also returns 403 when the organization has no user with the given ID, including a user that is deleted. ## OpenAPI ````yaml /openapi/findity-admin-api.json put /organizations/{organizationId}/users/{userId} openapi: 3.1.0 info: title: Findity Admin API description: Findity Admin API version: 1.0.0 servers: - url: https://stage-api.findity.com/api/v1/admin - url: https://api.findity.com/api/v1/admin security: - bearerAuth: [] paths: /organizations/{organizationId}/users/{userId}: put: tags: - Users summary: Update user description: > Changes a user of the given organization and returns it as the list returns it. Only the properties in the body are changed: a property that is left out keeps its value, and `null` clears an optional property. A user read from the list can be sent back, changed or not; leave out `language` when it is `null`. `email` and `ssn` can't be changed: the email address is the user's login and the identity number identifies the person. They are accepted when they equal the user's current values, otherwise the request is rejected. The read-only `id`, `lastInvitationDate` and `dateCreated` are ignored. The values get the same checks as when a user is created: unknown departments, dimensions, dimension values and languages, invalid bank account numbers, IBAN and BIC values, and an `endDate` in the past are rejected instead of ignored. An `endDate`, `bankAccountNumber`, `IBAN` or `BIC` sent back unchanged isn't checked again; the other values, such as `department` and `customDimensionPresetValues`, are checked even when unchanged. No other user of the organization may have the same `externalSourceId` or `employeeId`. `firstName`, `lastName`, `mobilePhone`, `language`, `bankAccountNumber`, `IBAN` and `BIC` belong to the person behind the user, which every organization employing that person shares. While the person is also a (not deleted) user of another organization, these can't be changed, so one organization can't change another's data or redirect its reimbursements: they are accepted when they equal the current values, otherwise the request is rejected with 400 and code `INVALID_JSON_PROPERTY_VALUE`, and nothing is changed. Bank details count as unchanged when they only differ in formatting, such as spaces or dashes. The properties of the employment itself, such as `employeeId`, `department` and `isAdministrator`, can still be changed. Making a user an administrator also gives them the organization administrator role. A changed department only changes the user's department; reports already sent for approval keep their approvers. Returns 403 when the organization does not exist or the authenticated user is not an administrator of it, so a caller cannot tell an organization they lack access to from a missing one. Also returns 403 when the organization has no user with the given ID, including a user that is deleted. operationId: adminUpdateOrganizationUser parameters: - name: organizationId in: path required: true description: > Required. String. Identifies the organization of the user. Accepts either the organization's internal ID (32-character hexadecimal string) or its `externalSourceId` (the string an integration set on the organization). This endpoint supports externalId: when the value has the format of an internal ID and an organization with that ID exists, the internal ID takes precedence; otherwise the value is looked up as `externalSourceId`. schema: type: string example: 11adfe2a080040e3892ffb89c21ec44e - name: userId in: path required: true description: > Required. String. Identifies the user to update, as returned in the `id` or `externalSourceId` field of the list response: either the user's internal ID (32-character hexadecimal string) or its `externalSourceId` (the non-empty string an integration set on the user). Only the users of the given organization are searched. This endpoint supports externalId: when a user of the organization has that internal ID, the internal ID takes precedence; otherwise the value is looked up as `externalSourceId`. schema: type: string example: 8a6c2f0e5b1d4c7f9e3a2b1c0d9e8f7a requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdminApiUserUpdate' example: title: Senior Engineering Lead mobilePhone: '+46701740605' department: externalSourceId: SAP-4711 customDimensionPresetValues: - dimensionDefinitionId: a1b2c3d4e5f60718293a4b5c6d7e8f90 presetListValueId: c0ffee00c0ffee00c0ffee00c0ffee00 endDate: null isAdministrator: true responses: '200': description: OK — the updated user content: application/json: schema: $ref: '#/components/schemas/AdminApiUser' example: id: 8a66aa549e6a3672019e73b79f8e1a7f externalSourceId: Erik_Exempel employeeId: E-1001 title: Engineering Lead firstName: Erik lastName: Exempel email: erik.exempel@example.com mobilePhone: '+46701740605' endDate: '2027-01-31T00:00:00Z' ssn: '1212121212' department: id: 9360d03ad7294220868d67f42a2a144d externalSourceId: null customDimensionPresetValues: - id: 5d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a dimensionDefinitionId: c2a0b3f4d5e64f7a8b9c0d1e2f3a4b5c presetListValueId: null presetListValueText: null presetStringValue: Project X language: en_GB bankAccountNumber: '95621537876' IBAN: SE4550000000058398257466 BIC: ESSESESS lastInvitationDate: null dateCreated: '2026-10-13T12:31:14Z' isAdministrator: false '400': description: > Bad request — the body is invalid, has a string property longer than 255 characters, tries to change `email` or `ssn`, tries to change the person's name, mobile phone, language or bank details while the person is also a user of another organization, or gives the user an `externalSourceId` or `employeeId` another user of the organization already has content: application/json: schema: $ref: '#/components/schemas/400Error' examples: Value too long: summary: > A string property is longer than 255 characters; the description names the first such property value: result: error code: FIELD_EXCEEDS_MAX_LENGTH description: title exceeds maximum length of 255 characters. Email changed: value: result: error code: INVALID_JSON_PROPERTY_VALUE description: email can't be changed Ssn changed: value: result: error code: INVALID_JSON_PROPERTY_VALUE description: ssn can't be changed Shared person data changed: summary: > The person is also a user of another organization; the description names the first changed property value: result: error code: INVALID_JSON_PROPERTY_VALUE description: >- IBAN can't be changed: the user is employed by another organization too Empty name: value: result: error code: INVALID_JSON_PROPERTY_VALUE description: firstName can't be empty External source id already used: summary: > Another user of the organization already has the `externalSourceId`; the description is the generic text of `EMPLOYEE_ALREADY_EXISTS` value: result: error code: EMPLOYEE_ALREADY_EXISTS description: The employee ID already exists. Employee ID already used: summary: >- Another user of the organization already has the `employeeId` value: result: error code: EMPLOYEE_ID_ALREADY_TAKEN description: >- Cannot set employeeId E-1001, it's already used in this organization Invalid end date: value: result: error code: INVALID_DATE description: Invalid date. Please verify it. Unknown language: value: result: error code: INVALID_LANGUAGE description: 'Unknown language: xx_XX' Unknown department: value: result: error code: INVALID_JSON_PROPERTY_VALUE description: Department not found Unknown dimension: value: result: error code: INVALID_JSON_PROPERTY_VALUE description: 'Dimension not found: c2a0b3f4d5e64f7a8b9c0d1e2f3a4b5c' Invalid IBAN: value: result: error code: INVALID_JSON_PROPERTY_VALUE description: Invalid IBAN Invalid bank account number: value: result: error code: INVALID_JSON_PROPERTY_VALUE description: Invalid bankAccountNumber for country SE No known properties: value: result: error code: NO_KNOWN_JSON_PROPERTIES description: No known, or only read-only properties received Malformed body: value: result: error code: INVALID_JSON_BODY description: Could not parse JSON content. '403': description: > Forbidden — the organization was not found or access is denied, or the organization has no user with the given ID (also when the user is deleted) content: application/json: schema: $ref: '#/components/schemas/403Error' examples: Organization not found or access denied: value: result: error description: Organization not found or access denied User not found or access denied: value: result: error description: User not found or access denied components: schemas: AdminApiUserUpdate: type: object description: > The properties of a user to change. Only the properties in the body are changed; a property that is left out keeps its value, and `null` clears an optional property. The properties have the same names and formats as in the list response, so a listed user can be sent back: `email` and `ssn` are accepted when they equal the user's current values, and the read-only properties `id`, `lastInvitationDate` and `dateCreated` are ignored. Leave out `language` when the list returns `null` for it, since `null` is rejected. `email`, `firstName`, `lastName`, `externalSourceId`, `employeeId`, `title`, `mobilePhone` and `bankAccountNumber` can be at most 255 characters long after leading and trailing whitespace is removed, and a text dimension's `presetStringValue` at most 255 characters; a longer value is rejected with 400 `FIELD_EXCEEDS_MAX_LENGTH` and nothing is changed. The limit is checked on every value in the body, also on one sent back unchanged; a value the list returns always fits, since the stored values are at most 255 characters. Apart from that length check, an `endDate`, `bankAccountNumber`, `IBAN` or `BIC` sent back unchanged isn't validated again; the other values, such as `department` and `customDimensionPresetValues`, are validated even when unchanged. `firstName`, `lastName`, `mobilePhone`, `language`, `bankAccountNumber`, `IBAN` and `BIC` belong to the person, whom every organization employing them shares: while the person is also a (not deleted) user of another organization, they are accepted only when they equal the current values, otherwise the request is rejected with 400 `INVALID_JSON_PROPERTY_VALUE` and nothing is changed. Bank details that only differ in formatting, such as spaces or dashes, count as unchanged. properties: email: type: string maxLength: 255 format: email description: > Can't be changed. String. The user's email address, which is also their login. Accepted only when it is the user's current email address (case-insensitive), otherwise 400 `INVALID_JSON_PROPERTY_VALUE`. At most 255 characters after leading and trailing whitespace is removed, otherwise 400 `FIELD_EXCEEDS_MAX_LENGTH`. ssn: type: - string - 'null' description: > Can't be changed. String. The user's personal identity number. Accepted only when it is the user's current number, written in any accepted format (`19121212-1212` matches a stored `1212121212`), otherwise 400 `INVALID_JSON_PROPERTY_VALUE`. firstName: type: string maxLength: 255 description: > Optional. String. The user's first name. Can't be empty or `null`. Can't be changed while the person is also a user of another organization: then accepted only when equal to the current value, otherwise 400 `INVALID_JSON_PROPERTY_VALUE`. At most 255 characters after leading and trailing whitespace is removed, otherwise 400 `FIELD_EXCEEDS_MAX_LENGTH`. lastName: type: string maxLength: 255 description: > Optional. String. The user's last name. Can't be empty or `null`. Can't be changed while the person is also a user of another organization: then accepted only when equal to the current value, otherwise 400 `INVALID_JSON_PROPERTY_VALUE`. At most 255 characters after leading and trailing whitespace is removed, otherwise 400 `FIELD_EXCEEDS_MAX_LENGTH`. externalSourceId: type: - string - 'null' maxLength: 255 description: > Optional. String. Identifier of the user in an external system. No other user of the organization may have it. `null` clears it. At most 255 characters after leading and trailing whitespace is removed, otherwise 400 `FIELD_EXCEEDS_MAX_LENGTH`. employeeId: type: - string - 'null' maxLength: 255 description: > Optional. String. The user's employee number in the organization. No other user of the organization may have it. `null` clears it. At most 255 characters after leading and trailing whitespace is removed, otherwise 400 `FIELD_EXCEEDS_MAX_LENGTH`. title: type: - string - 'null' maxLength: 255 description: > Optional. String. The user's job title. `null` clears it. At most 255 characters after leading and trailing whitespace is removed, otherwise 400 `FIELD_EXCEEDS_MAX_LENGTH`. mobilePhone: type: - string - 'null' maxLength: 255 description: > Optional. String. The user's mobile phone number in international format (e.g. `+46701234567`). `null` clears it. A user whose mobile number is verified keeps that number: a different number or `null` is ignored, and the request still answers 200. Can't be changed while the person is also a user of another organization: then accepted only when equal to the current value, otherwise 400 `INVALID_JSON_PROPERTY_VALUE`. At most 255 characters after leading and trailing whitespace is removed, otherwise 400 `FIELD_EXCEEDS_MAX_LENGTH`. endDate: type: - string - 'null' format: date-time description: > Optional. ISO-8601 date-time in UTC (`yyyy-MM-ddTHH:mm:ssZ`). The date the user's employment ends. A new value can't be in the past. `null` clears it. department: type: - object - 'null' description: > Optional. The department (organizational unit) of the organization to place the user in, identified by either `id` or `externalSourceId`; at least one of them is required. When both are given, `id` is used. `null` removes the user from their department. anyOf: - required: - id - required: - externalSourceId properties: id: type: - string - 'null' description: > String. The department's ID, as returned in `id` by the department endpoints. externalSourceId: type: - string - 'null' description: >- String. The department's `externalSourceId`, the non-empty string an integration set on it. customDimensionPresetValues: type: - array - 'null' description: > Optional. Custom dimension values to preset on the user, used as defaults on the user's expenses. The list replaces the user's preset values: a dimension left out of it loses its preset value, and `null` or `[]` removes them all. The other properties of a listed preset value are ignored. items: type: object required: - dimensionDefinitionId properties: dimensionDefinitionId: type: string description: >- Required. String. The ID of a custom dimension definition of the organization. presetListValueId: type: - string - 'null' description: > String. Required for a dimension with a list of values, the ID of one of the list's values. presetStringValue: type: - string - 'null' maxLength: 255 description: > String. For a text dimension, the preset text. At most 255 characters, counted as sent; a longer value is rejected with 400 `FIELD_EXCEEDS_MAX_LENGTH`. language: type: string description: > Optional. String. The user's language and region as a locale code (`language_COUNTRY`, e.g. `en_GB`, `sv_SE`). Can't be `null`: leave it out for a user the list returns with `language: null`. Can't be changed while the person is also a user of another organization: then accepted only when equal to the current value, otherwise 400 `INVALID_JSON_PROPERTY_VALUE`. bankAccountNumber: type: - string - 'null' maxLength: 255 description: > Optional. String. The user's bank account number for reimbursements, validated for the organization's country unless the client application turns that validation off. Stored without separators. `null` clears it. Can't be changed while the person is also a user of another organization: then accepted only when equal to the current value (ignoring formatting), otherwise 400 `INVALID_JSON_PROPERTY_VALUE`. At most 255 characters after leading and trailing whitespace is removed, otherwise 400 `FIELD_EXCEEDS_MAX_LENGTH`. IBAN: type: - string - 'null' description: > Optional. String. The user's International Bank Account Number for reimbursements. Spaces are allowed and removed; stored in upper case. `null` clears it. Can't be changed while the person is also a user of another organization: then accepted only when equal to the current value (ignoring formatting), otherwise 400 `INVALID_JSON_PROPERTY_VALUE`. BIC: type: - string - 'null' description: > Optional. String. The Bank Identifier Code (SWIFT code) of the user's bank. Spaces are allowed and removed; stored in upper case. `null` clears it. Can't be changed while the person is also a user of another organization: then accepted only when equal to the current value (ignoring formatting), otherwise 400 `INVALID_JSON_PROPERTY_VALUE`. isAdministrator: type: - boolean - 'null' description: > Optional. Boolean. True makes the user an administrator of the organization, false removes them as one. `null` leaves it unchanged. AdminApiUser: type: object description: > A user of an organization: a person employed by the organization. Every property is always present; properties without a value are null. required: - id - externalSourceId - employeeId - title - firstName - lastName - email - mobilePhone - endDate - ssn - department - customDimensionPresetValues - language - bankAccountNumber - IBAN - BIC - lastInvitationDate - dateCreated - isAdministrator properties: id: $ref: '#/components/schemas/Uuid' externalSourceId: type: - string - 'null' description: > String. Identifier of the user in an external system, set by an integration. Unique within the client application. Null when not set. employeeId: type: - string - 'null' description: >- String. The user's employee number in the organization. Null when not set. title: type: - string - 'null' description: String. The user's job title. Null when not set. firstName: type: string description: String. The user's first name. lastName: type: string description: String. The user's last name. email: type: string format: email description: String. The user's email address, also used to log in. mobilePhone: type: - string - 'null' description: > String. The user's mobile phone number as entered, usually in international format (e.g. `+46701234567`). Null when not set. endDate: type: - string - 'null' format: date-time description: > ISO-8601 date-time in UTC (`yyyy-MM-ddTHH:mm:ssZ`). The date the user's employment ends. Null when the employment has no end date. ssn: type: - string - 'null' description: > String. The user's personal identity number (social security number), as stored. A number entered by the user is stored normalized, for Swedish numbers without separator and century digits (e.g. `1212121212`). Null when not set. department: type: - object - 'null' description: >- The department (organizational unit) the user belongs to. Null when the user is not placed in a department. required: - id - externalSourceId properties: id: type: string description: >- String. The department's ID, as returned in `id` by the department endpoints. externalSourceId: type: - string - 'null' description: >- String. Identifier of the department in an external system, set by an integration. Null when not set. customDimensionPresetValues: type: array description: > Custom dimension values preset on the user, used as defaults on the user's expenses. Excludes values belonging to deleted dimension definitions. Empty when none are set. items: $ref: '#/components/schemas/AdminApiCustomDimensionPresetValue' language: type: - string - 'null' description: > String. The user's language and region as a locale code (`language_COUNTRY`, e.g. `en_GB`, `sv_SE`). Null when the user has not chosen a language, in which case the organization's language applies. bankAccountNumber: type: - string - 'null' description: >- String. The user's bank account number for reimbursements. Null when not set. IBAN: type: - string - 'null' description: >- String. The user's International Bank Account Number for reimbursements. Null when not set. BIC: type: - string - 'null' description: >- String. The Bank Identifier Code (SWIFT code) of the user's bank. Null when not set. lastInvitationDate: type: - string - 'null' format: date-time description: > ISO-8601 date-time in UTC (`yyyy-MM-ddTHH:mm:ssZ`). When the user was last sent an invitation email. Null when the user has not been invited, or has since activated their account. dateCreated: type: string format: date-time description: >- ISO-8601 date-time in UTC (`yyyy-MM-ddTHH:mm:ssZ`). When the user was added to the organization. isAdministrator: type: boolean description: Boolean. True when the user is an administrator of the organization. 400Error: type: object properties: result: type: string code: type: string description: type: string 403Error: type: object properties: result: type: string code: type: string description: type: string example: result: error description: Not allowed Uuid: type: string pattern: ^[0-9a-fA-F]{32}$ description: UUID without dashes (32-character hex string) AdminApiCustomDimensionPresetValue: type: object required: - id - dimensionDefinitionId properties: id: type: string description: Unique identifier of the preset value. dimensionDefinitionId: type: string description: >- The ID of the custom dimension definition this preset value belongs to. presetListValueId: type: - string - 'null' description: >- The ID of the selected list value, when the dimension uses a list of values. Null when a free-text preset is used instead. presetListValueText: type: - string - 'null' description: >- Display text of the selected list value. Null when a free-text preset is used instead. presetStringValue: type: - string - 'null' description: >- Free-text preset value, when the dimension does not use a list of values. Null when a list value is used instead. securitySchemes: bearerAuth: type: http scheme: bearer ````