> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getprimo.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create an onboarding for an existing employee
> Start the onboarding of an employee who already exists in Primo: creates the onboarding, its ticket and the "Confirm onboarding information" task, then the admins run the email, SaaS provisioning and equipment steps from the cockpit according to the onboarding settings. The employee must exist first — `createEmployee` only creates the record and never starts an onboarding, so call it, then this operation with the returned id. Refused when the employee already has an open onboarding (`ONBOARDING_ALREADY_EXISTS`), is synchronised from a connected HRIS (`EMPLOYEE_MANAGED_BY_HRIS` — that HRIS drives their onboarding), is hidden or has already left, when no start date is known (send `startDate` or set it on the employee first), or when onboarding tickets are not enabled for the company. A start date in the past is accepted for a joiner already in post. To act on an onboarding that already exists, use `getOnboardings`, `completeOnboarding`, `ignoreOnboarding` or `executeOnboardingEquipment` instead.
Key: WriteScope: Company
## OpenAPI
````yaml https://api.getprimo.com/openapi.json post /onboardings
openapi: 3.1.1
info:
title: Public API - BETA
description: Read docs on https://docs.getprimo.com/
version: '1.0'
contact: {}
servers:
- url: https://api.getprimo.com
security:
- apikey: []
tags: []
paths:
/onboardings:
post:
tags:
- Onboardings
summary: Create an onboarding for an existing employee
description: >-
Start the onboarding of an employee who already exists in Primo: creates
the onboarding, its ticket and the "Confirm onboarding information"
task, then the admins run the email, SaaS provisioning and equipment
steps from the cockpit according to the onboarding settings. The
employee must exist first — `createEmployee` only creates the record and
never starts an onboarding, so call it, then this operation with the
returned id. Refused when the employee already has an open onboarding
(`ONBOARDING_ALREADY_EXISTS`), is synchronised from a connected HRIS
(`EMPLOYEE_MANAGED_BY_HRIS` — that HRIS drives their onboarding), is
hidden or has already left, when no start date is known (send
`startDate` or set it on the employee first), or when onboarding tickets
are not enabled for the company. A start date in the past is accepted
for a joiner already in post. To act on an onboarding that already
exists, use `getOnboardings`, `completeOnboarding`, `ignoreOnboarding`
or `executeOnboardingEquipment` instead.
operationId: createOnboarding
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreateOnboardingBody'
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetOnboarding_Output'
components:
schemas:
CreateOnboardingBody:
type: object
properties:
employeeId:
description: >-
Primo employee id of the joiner. Get it from `getEmployees` or
`createEmployee`.
type: string
pattern: ^[a-f\d]{24}$
startDate:
description: >-
First day of the joiner (ISO 8601), past or future. Omit to use the
start date already on the employee record; when sent, the employee
record is updated to match.
anyOf:
- type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
- type: 'null'
required:
- employeeId
GetOnboarding_Output:
type: object
properties:
id:
type: string
employeeId:
anyOf:
- type: string
- type: 'null'
ticketId:
anyOf:
- type: string
- type: 'null'
status:
type: string
enum:
- PENDING
- SCHEDULED
- IN_PROGRESS
- CLOSED
- CANCELED
source:
type: string
enum:
- COCKPIT
- MERGE
- KOMBO
- API
suggestedEmail:
anyOf:
- type: string
- type: 'null'
startDate:
anyOf:
- type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
- type: 'null'
createdAt:
type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
hrRecords:
description: HR records from the connected HRIS (Kombo) for this onboarding
type: array
items:
type: object
properties:
id:
type: string
remoteId:
anyOf:
- type: string
- type: 'null'
firstName:
anyOf:
- type: string
- type: 'null'
lastName:
anyOf:
- type: string
- type: 'null'
email:
anyOf:
- type: string
- type: 'null'
personalEmail:
anyOf:
- type: string
- type: 'null'
phone:
anyOf:
- type: string
- type: 'null'
startDate:
anyOf:
- type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
- type: 'null'
terminationDate:
anyOf:
- type: string
format: date-time
pattern: >-
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
- type: 'null'
required:
- id
additionalProperties: false
required:
- id
- status
- source
- createdAt
- hrRecords
additionalProperties: false
securitySchemes:
apikey:
scheme: bearer
bearerFormat: API key
type: http
description: >-
Use your Primo API key in the Authorization header as `Bearer
`.
````