> ## 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.
# Update the onboarding settings
> Change the company onboarding settings — the steps every onboarding includes, their owners, due dates and scheduling, the default ticket owner, priority and subscribers, and the Primo AI agent options. Only the fields you send are changed; everything else keeps its stored value, so send just what the user asked to change rather than the whole object. `defaultTaskOwner`, `owner` and `defaultTaskSubscribers` take a Primo employee id (type EMPLOYEE) or the Clerk user id of an admin with no employee record (type EXTERNAL_ADMIN) — look the person up with getEmployees first; a person who does not belong to the company is refused. Sending null clears a field. The new settings apply to onboardings created afterwards, never to the ones already open. Call getOnboardingSettings first so you can tell the user what the change replaces.
Key: WriteScope: Company
## OpenAPI
````yaml https://api.getprimo.com/openapi.json patch /onboarding-settings
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:
/onboarding-settings:
patch:
tags:
- Onboardings
summary: Update the onboarding settings
description: >-
Change the company onboarding settings — the steps every onboarding
includes, their owners, due dates and scheduling, the default ticket
owner, priority and subscribers, and the Primo AI agent options. Only
the fields you send are changed; everything else keeps its stored value,
so send just what the user asked to change rather than the whole object.
`defaultTaskOwner`, `owner` and `defaultTaskSubscribers` take a Primo
employee id (type EMPLOYEE) or the Clerk user id of an admin with no
employee record (type EXTERNAL_ADMIN) — look the person up with
getEmployees first; a person who does not belong to the company is
refused. Sending null clears a field. The new settings apply to
onboardings created afterwards, never to the ones already open. Call
getOnboardingSettings first so you can tell the user what the change
replaces.
operationId: updateOnboardingSettings
parameters: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateOnboardingSettingsBody'
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetOnboardingSettings_Output'
components:
schemas:
UpdateOnboardingSettingsBody:
type: object
properties:
emailIncluded:
type: boolean
description: Whether the professional email step is part of every onboarding.
provisioningIncluded:
type: boolean
description: Whether the SaaS provisioning step is part of every onboarding.
equipmentIncluded:
type: boolean
description: Whether the equipment step is part of every onboarding.
equipmentHandledByAi:
type: boolean
description: >-
Whether the Primo AI agent drives the equipment step instead of a
human owner.
addPrimoAiAgent:
type: boolean
description: Whether the Primo AI agent is put on every onboarding ticket.
equipmentMdmEnrollment:
type: boolean
description: Whether ordered devices are enrolled in MDM automatically.
saasApplicationSuggestions:
type: boolean
description: Whether Primo suggests SaaS applications for the joiner.
emailCreationChoice:
type: string
description: >-
CREATE provisions a new address, EXISTING reuses the one the HRIS
carries.
enum:
- CREATE
- EXISTING
emailExistingAddressHandling:
anyOf:
- type: string
enum:
- USE_AS_IS
- MANUAL_CONFIRMATION
- type: 'null'
emailScheduling:
anyOf:
- type: object
properties:
numberDaysBefore:
description: >-
Days before the start date the step runs on. 0 means the
start date.
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
time:
description: Time of day the step runs at, as "HH:mm".
type: string
required:
- numberDaysBefore
- time
- type: 'null'
provisioningScheduling:
anyOf:
- type: object
properties:
numberDaysBefore:
description: >-
Days before the start date the step runs on. 0 means the
start date.
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
time:
description: Time of day the step runs at, as "HH:mm".
type: string
required:
- numberDaysBefore
- time
- type: 'null'
equipmentScheduling:
anyOf:
- type: object
properties:
numberDaysBefore:
description: >-
Days before the start date the step runs on. 0 means the
start date.
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
time:
description: Time of day the step runs at, as "HH:mm".
type: string
required:
- numberDaysBefore
- time
- type: 'null'
automaticProcessingActions:
type: array
description: Steps Primo executes without waiting for an admin to validate them.
items:
type: string
enum:
- EMPLOYEE_INFORMATION
- EMPLOYEE_EMAIL
- EMPLOYEE_PROVISIONING
- EMPLOYEE_EQUIPMENT
defaultTaskOwner:
description: >-
Assignee of the onboarding ticket and of every step with no owner of
its own. Null means unassigned.
anyOf:
- type: object
properties:
type:
type: string
enum:
- EMPLOYEE
- EXTERNAL_ADMIN
employeeId:
description: >-
Primo employee id. Required when `type` is EMPLOYEE — get it
from `getEmployees`.
anyOf:
- type: string
- type: 'null'
userId:
description: >-
Clerk user id of an admin without an employee record.
Required when `type` is EXTERNAL_ADMIN.
anyOf:
- type: string
- type: 'null'
required:
- type
- type: 'null'
defaultTaskPriority:
anyOf:
- type: string
enum:
- LOW
- MEDIUM
- HIGH
- type: 'null'
defaultTaskSubscribers:
type: array
items:
type: object
properties:
type:
type: string
enum:
- EMPLOYEE
- EXTERNAL_ADMIN
employeeId:
description: >-
Primo employee id. Required when `type` is EMPLOYEE — get it
from `getEmployees`.
anyOf:
- type: string
- type: 'null'
userId:
description: >-
Clerk user id of an admin without an employee record. Required
when `type` is EXTERNAL_ADMIN.
anyOf:
- type: string
- type: 'null'
required:
- type
taskSettings:
description: Per-step overrides of owner, due date and scheduling.
type: array
items:
type: object
properties:
actionType:
type: string
enum:
- EMPLOYEE_INFORMATION
- EMPLOYEE_EMAIL
- EMPLOYEE_PROVISIONING
- EMPLOYEE_EQUIPMENT
owner:
description: Assignee of that step task. Falls back to `defaultTaskOwner`.
anyOf:
- type: object
properties:
type:
type: string
enum:
- EMPLOYEE
- EXTERNAL_ADMIN
employeeId:
description: >-
Primo employee id. Required when `type` is EMPLOYEE —
get it from `getEmployees`.
anyOf:
- type: string
- type: 'null'
userId:
description: >-
Clerk user id of an admin without an employee record.
Required when `type` is EXTERNAL_ADMIN.
anyOf:
- type: string
- type: 'null'
required:
- type
- type: 'null'
dueDateNumberDaysBefore:
description: Days before the start date the task is due.
anyOf:
- type: integer
minimum: -9007199254740991
maximum: 9007199254740991
- type: 'null'
scheduling:
anyOf:
- type: object
properties:
numberDaysBefore:
description: >-
Days before the start date the step runs on. 0 means
the start date.
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
time:
description: Time of day the step runs at, as "HH:mm".
type: string
required:
- numberDaysBefore
- time
- type: 'null'
required:
- actionType
GetOnboardingSettings_Output:
type: object
properties:
emailIncluded:
type: boolean
description: Whether the professional email step is part of every onboarding.
provisioningIncluded:
type: boolean
description: Whether the SaaS provisioning step is part of every onboarding.
equipmentIncluded:
type: boolean
description: Whether the equipment step is part of every onboarding.
equipmentHandledByAi:
type: boolean
description: >-
Whether the Primo AI agent drives the equipment step instead of a
human owner.
addPrimoAiAgent:
type: boolean
description: Whether the Primo AI agent is put on every onboarding ticket.
equipmentMdmEnrollment:
type: boolean
description: Whether ordered devices are enrolled in MDM automatically.
saasApplicationSuggestions:
type: boolean
description: Whether Primo suggests SaaS applications for the joiner.
emailCreationChoice:
type: string
description: >-
CREATE provisions a new address, EXISTING reuses the one the HRIS
carries.
enum:
- CREATE
- EXISTING
emailExistingAddressHandling:
anyOf:
- type: string
enum:
- USE_AS_IS
- MANUAL_CONFIRMATION
- type: 'null'
emailScheduling:
anyOf:
- type: object
properties:
numberDaysBefore:
description: >-
Days before the start date the step runs on. 0 means the
start date.
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
time:
description: Time of day the step runs at, as "HH:mm".
type: string
required:
- numberDaysBefore
- time
additionalProperties: false
- type: 'null'
provisioningScheduling:
anyOf:
- type: object
properties:
numberDaysBefore:
description: >-
Days before the start date the step runs on. 0 means the
start date.
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
time:
description: Time of day the step runs at, as "HH:mm".
type: string
required:
- numberDaysBefore
- time
additionalProperties: false
- type: 'null'
equipmentScheduling:
anyOf:
- type: object
properties:
numberDaysBefore:
description: >-
Days before the start date the step runs on. 0 means the
start date.
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
time:
description: Time of day the step runs at, as "HH:mm".
type: string
required:
- numberDaysBefore
- time
additionalProperties: false
- type: 'null'
automaticProcessingActions:
type: array
description: Steps Primo executes without waiting for an admin to validate them.
items:
type: string
enum:
- EMPLOYEE_INFORMATION
- EMPLOYEE_EMAIL
- EMPLOYEE_PROVISIONING
- EMPLOYEE_EQUIPMENT
defaultTaskOwner:
description: >-
Assignee of the onboarding ticket and of every step with no owner of
its own. Null means unassigned.
anyOf:
- type: object
properties:
type:
type: string
enum:
- EMPLOYEE
- EXTERNAL_ADMIN
employeeId:
description: >-
Primo employee id. Required when `type` is EMPLOYEE — get it
from `getEmployees`.
anyOf:
- type: string
- type: 'null'
userId:
description: >-
Clerk user id of an admin without an employee record.
Required when `type` is EXTERNAL_ADMIN.
anyOf:
- type: string
- type: 'null'
required:
- type
additionalProperties: false
- type: 'null'
defaultTaskPriority:
anyOf:
- type: string
enum:
- LOW
- MEDIUM
- HIGH
- type: 'null'
defaultTaskSubscribers:
type: array
items:
type: object
properties:
type:
type: string
enum:
- EMPLOYEE
- EXTERNAL_ADMIN
employeeId:
description: >-
Primo employee id. Required when `type` is EMPLOYEE — get it
from `getEmployees`.
anyOf:
- type: string
- type: 'null'
userId:
description: >-
Clerk user id of an admin without an employee record. Required
when `type` is EXTERNAL_ADMIN.
anyOf:
- type: string
- type: 'null'
required:
- type
additionalProperties: false
taskSettings:
type: array
description: Per-step overrides of owner, due date and scheduling.
items:
type: object
properties:
actionType:
type: string
enum:
- EMPLOYEE_INFORMATION
- EMPLOYEE_EMAIL
- EMPLOYEE_PROVISIONING
- EMPLOYEE_EQUIPMENT
owner:
description: Assignee of that step task. Falls back to `defaultTaskOwner`.
anyOf:
- type: object
properties:
type:
type: string
enum:
- EMPLOYEE
- EXTERNAL_ADMIN
employeeId:
description: >-
Primo employee id. Required when `type` is EMPLOYEE —
get it from `getEmployees`.
anyOf:
- type: string
- type: 'null'
userId:
description: >-
Clerk user id of an admin without an employee record.
Required when `type` is EXTERNAL_ADMIN.
anyOf:
- type: string
- type: 'null'
required:
- type
additionalProperties: false
- type: 'null'
dueDateNumberDaysBefore:
description: Days before the start date the task is due.
anyOf:
- type: integer
minimum: -9007199254740991
maximum: 9007199254740991
- type: 'null'
scheduling:
anyOf:
- type: object
properties:
numberDaysBefore:
description: >-
Days before the start date the step runs on. 0 means
the start date.
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
time:
description: Time of day the step runs at, as "HH:mm".
type: string
required:
- numberDaysBefore
- time
additionalProperties: false
- type: 'null'
required:
- actionType
additionalProperties: false
required:
- emailIncluded
- provisioningIncluded
- equipmentIncluded
- equipmentHandledByAi
- addPrimoAiAgent
- equipmentMdmEnrollment
- saasApplicationSuggestions
- emailCreationChoice
- automaticProcessingActions
- defaultTaskSubscribers
- taskSettings
additionalProperties: false
securitySchemes:
apikey:
scheme: bearer
bearerFormat: API key
type: http
description: >-
Use your Primo API key in the Authorization header as `Bearer
`.
````