---
title: "Creates an account in the organization, like Users → Add User in the app."
method: POST
path: "/api/v1/users"
tags: ["Users"]
---

# Creates an account in the organization, like Users → Add User in the app.

`POST /api/v1/users`

## Request

- Base URL: `https://app.flexonthejob.com`
- URL: `https://app.flexonthejob.com/api/v1/users`
- Auth: HTTP bearer

Requires `ManageUsers` and an `Idempotency-Key`. The sync server creates the account
(the same call the Add User page makes); it can sign in to the web app at once and on devices at
their next sign-in. The key's creator must be an OrganizationAdmin (or higher); `role` may be
at most the creator's own; SystemAdmin is never assignable; and every permission the new account
would get (its role's, plus `customRoleId`'s) must be held by the API key and by its creator.
The password must meet the Flex password rule and is never returned. An active account counts as
a billed seat once the organization is past its included seats. Example:
`{ "email": "sam@example.com", "firstName": "Sam", "lastName": "Carter", "password": "Welcome#2026", "role": "Manager" }`.

## Request body

- CreateUserApiRequest: Body of `POST /api/v1/users`. Example: `{ "email": "sam@example.com", "firstName": "Sam", "lastName": "Carter", "password": "Welcome#2026", "role": "Manager" }`.
  - `email` string, email, required: Login e-mail address, unique across Flex, up to 256 characters. Example: `"sam@example.com"`.
  - `firstName` string, required: First name, 1..100 characters. Example: `"Sam"`.
  - `lastName` string, required: Last name, 1..100 characters. Example: `"Carter"`.
  - `password` string, required: Initial password: at least 8 characters with an uppercase letter, a lowercase letter, a digit and a symbol. Pass it to the person securely; they can change it under Account → Settings. Never returned. Example: `"Welcome#2026"`.
  - `role` 'OrganizationAdmin' | 'Manager' | 'User': A standard role an API caller may assign. `SystemAdmin` is never assignable through the API. Ranked OrganizationAdmin (3) > Manager (2) > User (1).
  - `customRoleId` integer, nullable: Optional custom role id (from `GET /api/v1/roles`) to add. The account then gets `User` as its standard role, so leave `role` out or send `User`. Example: `4`.

## Response `201`

Created; `Location` points at the new account.

- UserDetailDto: An account of the calling organization, as returned by the user-administration endpoints (`GET /api/v1/users/{id}`, `POST /api/v1/users`, `PATCH /api/v1/users/{id}`). Never carries a password, hash or security stamp.
  - `id` string: User id (string GUID). Example: `"8f0c3c1e-2b6d-4c55-9a51-0d3f3c1b7e21"`.
  - `email` string, nullable: Login e-mail address. Example: `"sam@example.com"`.
  - `firstName` string, nullable: First name. Example: `"Sam"`.
  - `lastName` string, nullable: Last name. Example: `"Carter"`.
  - `displayName` string: Display name, e.g. `"Sam Carter"`; falls back to the e-mail address when no name is recorded.
  - `isActive` boolean: False when the account is deactivated (it cannot sign in and holds no seat).
  - `role` string, nullable: Highest standard role the account holds — `OrganizationAdmin`, `Manager` or `User` (`SystemAdmin` for platform staff); null when it holds only custom roles.
  - `customRoleIds` integer[]: Ids of the custom roles the account holds (see `/api/v1/roles`). Empty when none.
  - `permissions` string[]: Effective permissions from all of the account's roles, in catalog order. Example: `["ViewInventory", "ViewJobs"]`.

## Other responses

- `202`: The sync server created the account but this host has not received it yet (it appears after the next sync).
- `400`: Malformed body, an unknown `role`, or missing `Idempotency-Key`.
- `401`: Unauthorized
- `403`: A hierarchy or grant rule refused it (the detail says which).
- `409`: The key's creator is unknown on this server.
- `422`: A value is unacceptable: e-mail already in use, weak password, unknown `customRoleId`.
- `429`: Too Many Requests
- `502`: The sync server answered with an unexpected error.
- `503`: This server cannot reach the sync server (not registered or offline); nothing was created.

---

[API](https://skmtc.dev/flexonthejob/apis/flex-api.md) · [All operations](https://skmtc.dev/flexonthejob/apis/flex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/flexonthejob/apis/flex-api/revisions/19c8f4d27acf?raw)