> ## 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.
# Execute the equipment step of an onboarding
> Equip a joiner and close the Equipment step of their onboarding in one call: places the catalog order when `order` is provided, assigns devices and accessories from existing stock when `assignedFromInventory` is provided, then moves the step and its onboarding-ticket task to done and links the order to the ticket. Send neither when the joiner is already equipped — the step still closes. Returns the onboarding and the order placed, or `order: null` when nothing was purchased. This is the only way to close an onboarding Equipment step: `updateTaskStatus` refuses that task, and `createOrder` places an order without touching the onboarding. To buy for stock or outside an onboarding, use `createOrder` instead. To close a whole onboarding for someone already in post without ordering or provisioning anything, use `completeOnboarding` instead. Refused with `ONBOARDING_EQUIPMENT_ALREADY_EXECUTED` when the step is already done — that means the work happened, not that the call failed.
Key: WriteScope: Company
## OpenAPI
````yaml https://api.getprimo.com/openapi.json post /onboardings/{onboardingId}/equipment
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/{onboardingId}/equipment:
post:
tags:
- Onboardings
summary: Execute the equipment step of an onboarding
description: >-
Equip a joiner and close the Equipment step of their onboarding in one
call: places the catalog order when `order` is provided, assigns devices
and accessories from existing stock when `assignedFromInventory` is
provided, then moves the step and its onboarding-ticket task to done and
links the order to the ticket. Send neither when the joiner is already
equipped — the step still closes. Returns the onboarding and the order
placed, or `order: null` when nothing was purchased. This is the only
way to close an onboarding Equipment step: `updateTaskStatus` refuses
that task, and `createOrder` places an order without touching the
onboarding. To buy for stock or outside an onboarding, use `createOrder`
instead. To close a whole onboarding for someone already in post without
ordering or provisioning anything, use `completeOnboarding` instead.
Refused with `ONBOARDING_EQUIPMENT_ALREADY_EXECUTED` when the step is
already done — that means the work happened, not that the call failed.
operationId: executeOnboardingEquipment
parameters:
- name: onboardingId
required: true
in: path
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteOnboardingEquipmentBody'
responses:
default:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ExecuteOnboardingEquipmentResult_Output'
components:
schemas:
ExecuteOnboardingEquipmentBody:
type: object
properties:
order:
description: Catalog order to place. Omit when nothing is purchased.
type: object
properties:
countryCode:
description: Catalog country code (lowercase ISO 3166-1 alpha-2)
type: string
enum:
- af
- al
- dz
- ad
- ao
- ag
- ar
- am
- au
- at
- az
- bs
- bh
- bd
- bb
- by
- be
- bz
- bj
- bt
- bo
- ba
- bw
- br
- bn
- bg
- bf
- bi
- cv
- kh
- cm
- ca
- cf
- td
- cl
- cn
- co
- km
- cg
- cr
- hr
- cu
- cy
- cz
- cd
- dk
- dj
- dm
- do
- ec
- eg
- sv
- gq
- er
- ee
- sz
- et
- fj
- fi
- fr
- ga
- gm
- ge
- de
- gh
- gr
- gd
- gt
- gn
- gw
- gy
- ht
- hn
- hu
- is
- in
- id
- ir
- iq
- ie
- il
- it
- jm
- jp
- jo
- kz
- ke
- ki
- kw
- kg
- la
- lv
- lb
- ls
- lr
- ly
- li
- lt
- lu
- mg
- mw
- my
- mv
- ml
- mt
- mh
- mr
- mu
- mx
- fm
- md
- mc
- mn
- me
- ma
- mz
- mm
- na
- nr
- np
- nl
- nz
- ni
- ne
- ng
- kp
- mk
- 'no'
- om
- pk
- pw
- pa
- pg
- py
- pe
- ph
- pl
- pt
- qa
- ro
- ru
- rw
- kn
- lc
- vc
- ws
- sm
- st
- sa
- sn
- rs
- sc
- sl
- sg
- sk
- si
- sb
- so
- za
- kr
- ss
- es
- lk
- sd
- sr
- se
- ch
- sy
- tw
- tj
- tz
- th
- tl
- tg
- to
- tt
- tn
- tr
- tm
- tv
- ug
- ua
- ae
- gb
- us
- uy
- uz
- vu
- va
- ve
- vn
- ye
- zm
- zw
products:
minItems: 1
type: array
items:
type: object
properties:
id:
description: Catalog product id
type: string
variantId:
description: Selected product variant id
type: string
supplierId:
description: Supplier id for this product
type: string
hasZTD:
type: boolean
configuration:
type: object
properties:
enableZTD:
type: boolean
enableACE:
type: boolean
required:
- enableZTD
- enableACE
required:
- id
- variantId
- supplierId
- configuration
shippingAddressType:
description: >-
Where the address comes from. HOME also back-fills the employee
record when it has no address yet, so send it whenever the
address is the employee's own.
anyOf:
- type: string
enum:
- OFFICE
- HOME
- NEW
- type: 'null'
shippingAddress:
description: >-
Delivery address. Take it from `getCompanyAddresses` or from the
employee record — never compose one.
type: object
properties:
name:
anyOf:
- type: string
- type: 'null'
contactName:
anyOf:
- type: string
- type: 'null'
phone:
description: Send null when no phone number is known.
anyOf:
- type: string
- type: 'null'
street:
type: string
minLength: 1
complement:
anyOf:
- type: string
- type: 'null'
postalCode:
type: string
minLength: 1
city:
type: string
minLength: 1
country:
anyOf:
- type: string
- type: 'null'
countryCode:
anyOf:
- type: string
- type: 'null'
required:
- phone
- street
- postalCode
- city
billingProfileId:
description: An eligible company billing profile id
anyOf:
- type: string
minLength: 1
- type: 'null'
notificationEmails:
type: array
items:
type: string
internalComment:
anyOf:
- type: string
minLength: 1
- type: 'null'
companyComment:
anyOf:
- type: string
minLength: 1
- type: 'null'
appleCareEnterprise:
anyOf:
- type: string
- type: 'null'
companyPurchaseNumber:
anyOf:
- type: string
- type: 'null'
required:
- countryCode
- products
- shippingAddress
assignedFromInventory:
description: >-
Devices and accessories taken from existing stock and assigned to
the employee.
type: object
properties:
deviceIds:
type: array
items:
type: string
accessoryIds:
type: array
items:
type: string
required:
- deviceIds
- accessoryIds
automaticEnrollment:
description: Leave unset to keep the onboarding current setting.
type: boolean
sendToPersonalEmail:
description: Leave unset to keep the onboarding current setting.
type: boolean
ExecuteOnboardingEquipmentResult_Output:
type: object
properties:
onboarding:
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
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
order:
description: >-
The order that was placed, or null when the step was executed
without a purchase.
anyOf:
- type: object
properties:
id:
type: string
reference:
type: string
status:
type: string
required:
- id
- reference
- status
additionalProperties: false
- type: 'null'
required:
- onboarding
additionalProperties: false
securitySchemes:
apikey:
scheme: bearer
bearerFormat: API key
type: http
description: >-
Use your Primo API key in the Authorization header as `Bearer
`.
````