> ## Documentation Index
> Fetch the complete documentation index at: https://docs.accessowl.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Update a user
> Updates the given fields of the user; omitted fields stay untouched and null clears a field. A user managed by an HRIS directory integration gets its name and org info from the directory, so these fields are refused. Its manager can only be changed together with manager_override set to true, which stops the directory sync from changing the manager; manager_override false hands the manager back to the directory.
Only the fields you send are changed — omitted fields stay untouched, and sending `null`
clears a field.
For a user managed by an **HRIS directory integration**, name and org info come from the
directory, so those fields are refused. The manager can only be changed together with
`manager_override: true`, which stops the directory sync from overwriting it; sending
`manager_override: false` hands the manager back to the directory.
Set a user's org info and manager here before [onboarding](/api-reference/users/onboard) —
onboarding requires the user to have a manager.
## OpenAPI
````yaml PATCH /api/v1/users/{id}
openapi: 3.0.0
info:
description: REST API for AccessOwl third-party integrations
title: AccessOwl API
version: 1.0.0
servers:
- url: https://api.accessowl.com
variables: {}
security:
- bearer: []
tags: []
paths:
/api/v1/users/{id}:
patch:
tags:
- users
summary: Update a user
description: >-
Updates the given fields of the user; omitted fields stay untouched and
null clears a field. A user managed by an HRIS directory integration
gets its name and org info from the directory, so these fields are
refused. Its manager can only be changed together with manager_override
set to true, which stops the directory sync from changing the manager;
manager_override false hands the manager back to the directory.
operationId: AccessOwlApi.StaffController.update (2)
parameters:
- description: >-
Optional key (1–255 chars) for safely retrying a request. Reusing
the same key for the same request returns `409 Conflict` and is not
processed again — this confirms the request was already received.
Keys are retained for 14 days.
in: header
name: Idempotency-Key
required: false
schema:
maxLength: 255
minLength: 1
type: string
- description: User ID
in: path
name: id
required: true
schema:
format: uuid
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUser'
description: Update user parameters
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/User'
description: User updated
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Not found
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Validation error
callbacks: {}
components:
schemas:
UpdateUser:
description: >-
Request body for updating a user. Omitted fields stay untouched; null
clears a field. For a user managed by an HRIS directory integration,
name and org-info fields are refused and a manager change requires
manager_override.
example:
job_title: Senior Software Engineer
manager_user_id: 7488a646-e31f-11e4-aace-600308960663
teams:
- Engineering
- Backend
properties:
departments:
description: Departments the user belongs to
items:
type: string
type: array
employment_type:
description: Employment type
enum:
- full_time
- part_time
- contract
- freelance
- internship
- apprenticeship
- working_student
- training
nullable: true
type: string
first_name:
description: First name
type: string
job_title:
description: Job title
nullable: true
type: string
last_name:
description: Last name
type: string
location_city:
description: City location
nullable: true
type: string
manager_override:
description: >-
Only relevant for a user managed by an HRIS directory integration.
true is required to change the manager and stops the directory sync
from changing it; false hands the manager back to the directory.
type: boolean
manager_user_id:
description: >-
Manager user ID. The user's own ID marks them as an executive, who
reports to no one.
format: uuid
nullable: true
type: string
teams:
description: Teams the user belongs to
items:
type: string
type: array
title: UpdateUser
type: object
User:
description: A user in the organization
example:
deactivated_at: null
departments:
- Engineering
email: john@example.com
employment_type: full_time
first_name: John
full_name: John Doe
id: 7488a646-e31f-11e4-aace-600308960662
inserted_at: '2023-01-01T00:00:00Z'
job_title: Software Engineer
last_name: Doe
location_city: San Francisco
manager_user_id: null
status: active
teams:
- Engineering
- Backend
updated_at: '2023-01-01T00:00:00Z'
properties:
deactivated_at:
description: Deactivation timestamp
format: date-time
nullable: true
type: string
departments:
description: Departments the user belongs to
items:
type: string
type: array
email:
description: Email address
format: email
type: string
employment_type:
description: Employment type
enum:
- full_time
- part_time
- contract
- freelance
- internship
- apprenticeship
- working_student
- training
nullable: true
type: string
first_name:
description: First name
type: string
full_name:
description: Full name (computed)
type: string
id:
description: User ID
format: uuid
type: string
inserted_at:
description: Creation timestamp
format: date-time
type: string
job_title:
description: Job title
nullable: true
type: string
last_name:
description: Last name
type: string
location_city:
description: City location
nullable: true
type: string
manager_user_id:
description: Manager user ID
format: uuid
nullable: true
type: string
status:
description: Current status
enum:
- active
- inactive
- onboarding
- onboarding_provisioning_planned
- offboarding
- offboarding_planned
- offboarded
type: string
teams:
description: Teams the user belongs to
items:
type: string
type: array
updated_at:
description: Last update timestamp
format: date-time
type: string
required:
- id
- first_name
- last_name
- email
- status
title: User
type: object
BadRequestError:
additionalProperties: false
description: Error response for a malformed or invalid request
example:
error: invalid_params
errors:
- field: application_id
messages:
- is invalid
message: Invalid request parameters
properties:
error:
description: Error code
example: invalid_params
type: string
errors:
description: >-
One entry per rejected parameter. Present when a query or path
parameter fails validation, and omitted for other bad requests.
items:
additionalProperties: false
properties:
field:
description: Name of the rejected parameter
example: application_id
type: string
messages:
description: Reasons the value was rejected
example:
- is invalid
items:
type: string
type: array
required:
- field
- messages
type: object
type: array
message:
description: Human-readable error message
example: Invalid request parameters
type: string
required:
- error
- message
title: BadRequestError
type: object
Error:
description: Standard error response
example:
error: not_found
message: Resource not found
properties:
error:
description: Error code
example: not_found
type: string
errors:
additionalProperties:
items:
type: string
type: array
description: >-
Field-specific validation errors, keyed by field name. Present on
422 responses. A 400 response reports its errors as a list instead —
see the BadRequestError schema.
example:
email:
- has invalid format
first_name:
- can't be blank
type: object
message:
description: Human-readable error message
example: Resource not found
type: string
required:
- error
- message
title: Error
type: object
securitySchemes:
bearer:
description: >-
Bearer token authentication. Pass your AccessOwl API token in the
`Authorization` header as `Bearer `.
scheme: bearer
type: http
````