> ## 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. # Create user > Adds a new user to the given organization and returns it as the list returns it. The user is created the same way as by the users import: a new person gets a pending account (or the status the organization's user setup prescribes), the organization's default language and country, and the license and employee-group defaults of the organization. No other user of the organization may have the same `email`, `externalSourceId` or `employeeId`; this endpoint never updates an existing user. When the client application shares person data across organizations, the `email` also can't belong to a person employed in another organization. Unknown departments, dimensions, dimension values and languages, and invalid bank account numbers, IBAN or BIC values are rejected instead of ignored. The person's address country is the organization's country; `ssn` and `bankAccountNumber` are validated for it. The user gets an invitation email when `sendInvitationMail` is `true`. When `sendInvitationMail` is left out, the user is invited if the calling client application sends invitations for activated organizations and the organization is activated. An organization whose user setup sends invitations to every new user invites them even when `sendInvitationMail` is `false`. Returns 404 when the organization does not exist, can't have users, 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. ## OpenAPI ````yaml /openapi/findity-admin-api.json post /organizations/{organizationId}/users 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: post: tags: - Users summary: Create user description: > Adds a new user to the given organization and returns it as the list returns it. The user is created the same way as by the users import: a new person gets a pending account (or the status the organization's user setup prescribes), the organization's default language and country, and the license and employee-group defaults of the organization. No other user of the organization may have the same `email`, `externalSourceId` or `employeeId`; this endpoint never updates an existing user. When the client application shares person data across organizations, the `email` also can't belong to a person employed in another organization. Unknown departments, dimensions, dimension values and languages, and invalid bank account numbers, IBAN or BIC values are rejected instead of ignored. The person's address country is the organization's country; `ssn` and `bankAccountNumber` are validated for it. The user gets an invitation email when `sendInvitationMail` is `true`. When `sendInvitationMail` is left out, the user is invited if the calling client application sends invitations for activated organizations and the organization is activated. An organization whose user setup sends invitations to every new user invites them even when `sendInvitationMail` is `false`. Returns 404 when the organization does not exist, can't have users, 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. operationId: adminCreateOrganizationUser parameters: - name: organizationId in: path required: true description: > Required. String. Identifies the organization the user is added to. 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: sendInvitationMail in: query required: false description: > Optional. Boolean. `true` sends the new user an invitation email, `false` doesn't (unless the organization's user setup invites every new user). When left out, the user is invited only if the calling client application sends invitations for activated organizations and the organization is activated. schema: type: boolean example: true requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdminApiUserCreate' example: email: erik.exempel@example.com firstName: Erik lastName: Exempel externalSourceId: Erik_Exempel employeeId: E-1001 title: Engineering Lead mobilePhone: '+46701740605' endDate: '2027-01-31T00:00:00Z' ssn: 19121212-1212 department: id: 9360d03ad7294220868d67f42a2a144d customDimensionPresetValues: - dimensionDefinitionId: c2a0b3f4d5e64f7a8b9c0d1e2f3a4b5c presetStringValue: Project X language: en_GB bankAccountNumber: 9562-1537876 IBAN: SE45 5000 0000 0583 9825 7466 BIC: ESSESESS isAdministrator: false responses: '201': description: Created — the new 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, a string property is longer than 255 characters, or the user already exists in the organization. When the users import rejects the email, ssn or mobile phone, the response is `FAILED_TO_ADD_PERSON_WITH_EMAIL` with the fixed description `validationErrors` and the posted email in `data.email`; it doesn't say which field failed. content: application/json: schema: $ref: '#/components/schemas/AdminApiUserCreate400Error' examples: Missing required property: value: result: error code: INVALID_JSON_PROPERTY_VALUE description: firstName is required 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. User already exists: value: result: error code: EMPLOYEE_ALREADY_EXISTS description: The employee ID already exists. Employee ID already used: 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 Invalid email, ssn or mobile phone: value: result: error code: FAILED_TO_ADD_PERSON_WITH_EMAIL description: validationErrors data: email: erik.exempel@example.com Malformed body: value: result: error code: INVALID_JSON_BODY description: Could not parse JSON content. No known properties: value: result: error code: NO_KNOWN_JSON_PROPERTIES description: No known, or only read-only properties received '404': description: > Not found — the organization does not exist, can't have users, or the authenticated user is not an administrator of it content: application/json: schema: $ref: '#/components/schemas/404Error' examples: Organization not found: value: result: error code: ORGANIZATION_NOT_FOUND description: Organization not found for id='no-such-organization' No access to the organization: value: result: error code: ORGANIZATION_NOT_FOUND description: Organization not found components: schemas: AdminApiUserCreate: type: object description: > A new user of an organization. The properties have the same names and formats as in the list response, so a listed user can be posted as is: `null` for an optional property means it isn't set, and the read-only properties `id`, `lastInvitationDate` and `dateCreated` are ignored. `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`. Unless a property states otherwise, the other string properties have no validated length or pattern. required: - email - firstName - lastName properties: email: type: string maxLength: 255 format: email description: > Required. String. The user's email address, also used to log in. No other user of the organization may have it; a deleted user's email address can be reused. At most 255 characters after leading and trailing whitespace is removed, otherwise 400 `FIELD_EXCEEDS_MAX_LENGTH`. firstName: type: string maxLength: 255 description: > Required. String. The user's first name. At most 255 characters after leading and trailing whitespace is removed, otherwise 400 `FIELD_EXCEEDS_MAX_LENGTH`. lastName: type: string maxLength: 255 description: > Required. String. The user's last name. 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. 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. 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. 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`). 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. Can't be in the past. ssn: type: - string - 'null' description: > Optional. String. The user's personal identity number (social security number), validated for the organization's country. Stored normalized, for Swedish numbers without separator and century digits (`19121212-1212` is stored as `1212121212`). No other person may have 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. 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 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 - 'null' description: > Optional. String. The user's language and region as a locale code (`language_COUNTRY`, e.g. `en_GB`, `sv_SE`). Defaults to the organization's language. 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 (`9562-1537876` is stored as `95621537876`). 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. 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. isAdministrator: type: - boolean - 'null' description: >- Optional. Boolean. True makes the user an administrator of the organization. Defaults to false. 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. AdminApiUserCreate400Error: type: object properties: result: type: string code: type: string description: type: string data: type: object description: > Only present for `FAILED_TO_ADD_PERSON_WITH_EMAIL`, where it holds the email address of the user that could not be added. properties: email: type: string format: email 404Error: type: object properties: result: type: string code: type: string description: type: string example: result: error code: ORGANIZATION_NOT_FOUND description: 'Failed to get organization for id: {orgId}' 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 ````