ACaccessowl
users

Create and onboard a user

Changed on

Creates a new user with the given identity, org info and manager, and onboards them via the Zero-Touch (access-template) flow in one step. Omit scheduled_at to provision now; a future timestamp defers provisioning. Nothing is created when onboarding cannot start. Fails if a user with the email already exists — onboard an existing user with POST /users/{user_id}/onboard.

post/api/v1/users/onboard

Request

  • Base URL
    https://app.accessowl.io
  • URL
    https://app.accessowl.io/api/v1/users/onboard
  • Auth
    HTTP bearer

Headers

Idempotency-Keystring

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.

Request body

departmentsstring[]

Departments the user belongs to

emailstring email required

Email address

employment_type'full_time' | 'part_time' | 'contract' | 'freelance' | 'internship' | 'apprenticeship' | 'working_student' | 'training' nullable

Employment type

first_namestring required

First name

job_titlestring nullable

Job title

last_namestring required

Last name

location_citystring nullable

City location

manager_user_idstring uuid required

Manager (user)

scheduled_atstring date-time nullable

When to provision access. Omitted or null provisions now; a future ISO 8601 timestamp defers it.

teamsstring[]

Teams the user belongs to

Example request

{
  "departments": [
    "Engineering"
  ],
  "email": "john@example.com",
  "first_name": "John",
  "job_title": "Software Engineer",
  "last_name": "Doe",
  "manager_user_id": "7488a646-e31f-11e4-aace-600308960663",
  "scheduled_at": "2026-12-31T09:00:00Z"
}

Response

User created and onboarding triggered

deactivated_atstring date-time nullable

Deactivation timestamp

departmentsstring[]

Departments the user belongs to

emailstring email required

Email address

employment_type'full_time' | 'part_time' | 'contract' | 'freelance' | 'internship' | 'apprenticeship' | 'working_student' | 'training' nullable

Employment type

first_namestring required

First name

full_namestring

Full name (computed)

idstring uuid required

User ID

inserted_atstring date-time

Creation timestamp

job_titlestring nullable

Job title

last_namestring required

Last name

location_citystring nullable

City location

manager_user_idstring uuid nullable

Manager user ID

offboarding_scheduled_atstring date-time nullable

When the planned offboarding starts

onboarding_scheduled_atstring date-time nullable

When the planned onboarding starts provisioning

status'active' | 'inactive' | 'onboarding' | 'onboarding_provisioning_planned' | 'offboarding' | 'offboarding_planned' | 'offboarded' required

Current status

teamsstring[]

Teams the user belongs to

updated_atstring date-time

Last update timestamp

Example response

{
  "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,
  "offboarding_scheduled_at": null,
  "onboarding_scheduled_at": null,
  "status": "active",
  "teams": [
    "Engineering",
    "Backend"
  ],
  "updated_at": "2023-01-01T00:00:00Z"
}

Changes

  • 5a1f071e40d8Revision changes
    • breaking

      response property errors/additionalProperties/items/ list-of-types was widened by adding types object to media type application/json of response 422

    • breaking

      removed the required property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      added the new forbidden enum value to the response property for the response status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the optional property to the response with the status

  • 1cc0fedf0bf8Revision changes
    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status