---
title: "Edits an account; only the fields sent change."
method: PATCH
path: "/api/v1/users/{id}"
tags: ["Users"]
---

# Edits an account; only the fields sent change.

`PATCH /api/v1/users/{id}`

## Request

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

Requires `ManageUsers` and an `Idempotency-Key`. The account must belong to the
organization, must not be the key creator's own, and must hold a strictly lesser role than the
creator (an OrganizationAdmin manages Managers and Users). `role` may rank up to the creator's
own, so an OrganizationAdmin can promote a Manager or User to `OrganizationAdmin`. `role` and `isActive` go through the sync server like the user list's buttons;
names and `customRoleIds` are written here. Whatever the edit adds to the account's
permissions (all of them when it reactivates the account) must be held by the API key and its
creator. Demoting or deactivating an Organization Admin is refused (403): use
`POST /api/v1/users/{id}/removal-requests` (their approval or 14 days' notice). Every rule is
checked before anything changes. Example:
`PATCH /api/v1/users/8f0c3c1e-2b6d-4c55-9a51-0d3f3c1b7e21 { "role": "Manager", "customRoleIds": [4] }`.

## Path parameters

- `id` string, required

## Request body

- UpdateUserApiRequest: Body of `PATCH /api/v1/users/{id}`; only the fields sent change. Example: `{ "role": "Manager", "customRoleIds": [4] }`.
  - `firstName` string, nullable: New first name, 1..100 characters. Example: `"Samantha"`.
  - `lastName` string, nullable: New last name, 1..100 characters. Example: `"Carter"`.
  - `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).
  - `isActive` boolean, nullable: `false` deactivates the account, `true` reactivates it (same as the deactivate / reactivate endpoints).
  - `customRoleIds` integer[], nullable: The complete set of custom role ids the account should hold; `[]` removes all. Example: `[4, 7]`.

## Response `200`

The account after the edit.

- 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

- `400`: Malformed body, an unknown `role`, or missing `Idempotency-Key`.
- `401`: Unauthorized
- `403`: A hierarchy or grant rule refused it (the detail says which).
- `404`: No such user in this organization.
- `409`: The key's creator is unknown on this server, or the change would remove the organization's last active Organization Admin.
- `422`: A value is unacceptable (blank name, unknown custom role id).
- `429`: Too Many Requests
- `502`: The sync server answered with an unexpected error.
- `503`: This server cannot reach the sync server; the role / active changes were not made.

---

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