---
title: "Onboard a user"
method: POST
path: "/api/v1/users/{user_id}/onboard"
tags: ["users"]
---

# Onboard a user

`POST /api/v1/users/{user_id}/onboard`

## Request

- Base URL: `https://app.accessowl.io`
- URL: `https://app.accessowl.io/api/v1/users/{user_id}/onboard`
- Auth: HTTP bearer

Onboards the user via the Zero-Touch (access-template) flow: provisions the access the template rules match for the user's org info. Does not change the user — set org info and manager beforehand with PATCH /users/{user_id}; onboarding requires the user to have a manager. Omit scheduled_at to provision now; a future timestamp defers provisioning. Calling again for a user already onboarding reschedules the planned provisioning to the new scheduled_at (omit it to provision now); an onboarding already being provisioned can no longer be rescheduled.

## Path parameters

- `user_id` string, uuid, required

## Headers

- `Idempotency-Key` string

## Request body

- OnboardUser: Request body for onboarding a user via the Zero-Touch (access-template) flow. Omit scheduled_at to provision now; provide a future timestamp to defer provisioning to that date.
  - `scheduled_at` string, date-time, nullable: When to provision access. Omitted or null provisions now; a future ISO 8601 timestamp defers it. For a user already onboarding, this reschedules the planned provisioning.

## Response `200`

User onboarding triggered

- User: A user in the organization
  - `deactivated_at` string, date-time, nullable: Deactivation timestamp
  - `departments` string[]: Departments the user belongs to
  - `email` string, email, required: Email address
  - `employment_type` 'full_time' | 'part_time' | 'contract' | 'freelance' | 'internship' | 'apprenticeship' | 'working_student' | 'training', nullable: Employment type
  - `first_name` string, required: First name
  - `full_name` string: Full name (computed)
  - `id` string, uuid, required: User ID
  - `inserted_at` string, date-time: Creation timestamp
  - `job_title` string, nullable: Job title
  - `last_name` string, required: Last name
  - `location_city` string, nullable: City location
  - `manager_user_id` string, uuid, nullable: Manager user ID
  - `offboarding_scheduled_at` string, date-time, nullable: When the planned offboarding starts
  - `onboarding_scheduled_at` string, date-time, nullable: When the planned onboarding starts provisioning
  - `status` 'active' | 'inactive' | 'onboarding' | 'onboarding_provisioning_planned' | 'offboarding' | 'offboarding_planned' | 'offboarded', required: Current status
  - `teams` string[]: Teams the user belongs to
  - `updated_at` string, date-time: Last update timestamp

## Other responses

- `400`: Bad request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `409`: Conflict
- `422`: Validation error
- `429`: Too many requests

## Changes

- **2026-10-31** `5a1f071e40d8`: 2 breaking, 4 warning, 3 info
  - response property `errors/additionalProperties/items/` list-of-types was widened by adding types `object` to media type `application/json` of response `422`
  - removed the required property `message` from the response with the `401` status
  - removed the optional property `errors` from the response with the `401` status
  - removed the optional property `errors` from the response with the `403` status
  - …5 more
- **2026-09-30** `1cc0fedf0bf8`: 2 info
  - added the optional property `offboarding_scheduled_at` to the response with the `200` status
  - added the optional property `onboarding_scheduled_at` to the response with the `200` status
- **2026-09-30** `56ece6c3256d`: 6 warning
  - removed the request property `departments`
  - removed the request property `employment_type`
  - removed the request property `job_title`
  - removed the request property `location_city`
  - …2 more
- **2026-09-22** `1dba1160cea4`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/accessowl/apis/accessowl-api/changes/api/v1/users/:user_id/onboard/post.md)

---

[API](https://skmtc.dev/accessowl/apis/accessowl-api.md) - [All operations](https://skmtc.dev/accessowl/apis/accessowl-api/llms.txt) - [OpenAPI document](https://skmtc.dev/accessowl/apis/accessowl-api/revisions/ff38c63d8807?raw)