---
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`

## Request

- Base URL: `https://companySubDomain.bamboohr.com`
- URL: `https://companySubDomain.bamboohr.com/api/v1/employees/{employeeId}/onboarding-experiences`
- Auth: OAuth 2
  - Authorization code: `/authorize.php`
  - Token URL: `/token.php` scopes: `onboarding.write`
- TypeScript: <https://skmtc.dev/bamboohr/apis/bamboohr-api/docs/api/v1/employees/:employeeId/onboarding-experiences/post.ts> (a function with typed inputs; its response is checked against the schema)

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

## Changes

- **2026-11-03** `922fc15f43a7`: 1 info
  - api operation id `288aa996aba16d7a495c62321ea999a9` removed and replaced with `eeaff2c89c256799c225fa30b5b96c33`

[Operation history](https://skmtc.dev/bamboohr/apis/bamboohr-api/changes/api/v1/employees/:employeeId/onboarding-experiences/post.md)

---

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