---
title: "Create employee onboarding experience"
method: POST
path: "/api/v1/employees/{employeeId}/onboarding-experiences"
tags: ["Onboarding", "Public API"]
---

# Create employee onboarding experience

`POST /api/v1/employees/{employeeId}/onboarding-experiences`

Creates (starts) an onboarding experience workflow for the employee’s existing new hire packet instance. Requires the onboarding experience phase-1 and workflow framework company toggles. Optional sentDateTime may be supplied for workflow idempotency (ISO 8601 or legacy datetime string accepted when non-empty).

OAuth Scopes: onboarding.write

## Path parameters

- `employeeId` integer, required

## Request body

- object
  - `sentDateTime` string, nullable — Optional sent datetime for the packet when starting the experience (string).

## Response `201`

Created

- OnboardingExperiencePublicApi — Onboarding experience for public APIs; links to the new hire packet instance by id only.
  - `id` integer — Onboarding experience id (same as the new hire packet instance primary key).
  - `employeeId` integer — Employee this onboarding experience belongs to.
  - `newHirePacketId` integer — Primary key of the linked new hire packet instance (NHP row).
  - `nhpTemplateId` integer, nullable — Linked NHP template id, if any.
  - `nhpConfigurationId` integer, nullable — Linked NHP configuration id, if any.
  - `status` 'cancelled' | 'completed' | 'sent' | 'draft' — Derived lifecycle status for the linked new hire packet instance.

## Other responses

- `400` — Bad request
- `403` — Forbidden — missing OAuth permission, or onboarding experience phase-1 / workflow framework feature not enabled for the company.
- `409` — Conflict — an onboarding experience workflow already exists for this employee.
- `422` — Workflow instance could not be started or is not running.
- `500` — Internal server error

---

[API](https://skmtc.net/bamboohr/apis/bamboohr-api.md) · [All operations](https://skmtc.net/bamboohr/apis/bamboohr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bamboohr/bamboohr-api/revisions/19ebf391a399/schema)