Onboardings

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. For an EQUIPMENT_ORDER task on a ticket, use executeEquipmentOrderIntent instead, and for an EMPLOYEE_CREATION task executeEmployeeCreationIntent: a typed task completes only through its intent. 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. Providing an order requires the marketplace to be enabled for the company: when it is disabled, the call is refused with 403 MarketplaceDisabledError (a Primo admin must enable it). Handing over stock without an order is not affected.

POST

onboardings

{onboardingId}

equipment

Execute the equipment step of an onboarding

curl --request POST \
  --url https://api.getprimo.com/onboardings/{onboardingId}/equipment \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "automaticEnrollment": true
}
'

import requests

url = "https://api.getprimo.com/onboardings/{onboardingId}/equipment"

payload = { "automaticEnrollment": True }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({automaticEnrollment: true})
};

fetch('https://api.getprimo.com/onboardings/{onboardingId}/equipment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getprimo.com/onboardings/{onboardingId}/equipment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'automaticEnrollment' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getprimo.com/onboardings/{onboardingId}/equipment"

	payload := strings.NewReader("{\n  \"automaticEnrollment\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getprimo.com/onboardings/{onboardingId}/equipment")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"automaticEnrollment\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getprimo.com/onboardings/{onboardingId}/equipment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"automaticEnrollment\": true\n}"

response = http.request(request)
puts response.read_body

{
  "onboarding": {
    "id": "<string>",
    "status": "PENDING",
    "source": "COCKPIT",
    "createdAt": "2023-11-07T05:31:56Z",
    "hrRecords": [
      {
        "id": "<string>",
        "remoteId": "<string>",
        "firstName": "<string>",
        "lastName": "<string>",
        "email": "<string>",
        "personalEmail": "<string>",
        "phone": "<string>",
        "startDate": "2023-11-07T05:31:56Z",
        "terminationDate": "2023-11-07T05:31:56Z"
      }
    ],
    "emails": [
      "<string>"
    ],
    "employeeId": "<string>",
    "ticketId": "<string>",
    "stepModel": "ACTIONS",
    "stepProgress": {
      "done": 0,
      "total": 0
    },
    "startDate": "2023-11-07T05:31:56Z",
    "hire": {
      "firstName": "<string>",
      "lastName": "<string>",
      "emails": [
        "<string>"
      ],
      "agentNotes": [
        "<string>"
      ],
      "rawText": "<string>",
      "jobTitle": "<string>",
      "teamId": "<string>",
      "teamName": "<string>",
      "managerId": "<string>",
      "managerName": "<string>",
      "workLocationId": "<string>",
      "workLocationName": "<string>",
      "workMode": "REMOTE",
      "city": "<string>"
    }
  },
  "order": {
    "id": "<string>",
    "reference": "<string>",
    "status": "<string>"
  }
}

Key: Write Scope: Company

Authorizations

Authorization

string

header

required

Use your Primo API key in the Authorization header as Bearer <API_KEY>.

Path Parameters

onboardingId

string

required

Body

application/json

order

object

Catalog order to place. Omit when nothing is purchased.

Show child attributes

assignedFromInventory

object

Devices and accessories taken from existing stock and assigned to the employee.

Show child attributes

automaticEnrollment

boolean

Leave unset to keep the onboarding current setting.

Response

default - application/json

onboarding

object

required

Show child attributes

order

object | null

The order that was placed, or null when the step was executed without a purchase.

Show child attributes

Execute the equipment step of an onboarding

curl --request POST \
  --url https://api.getprimo.com/onboardings/{onboardingId}/equipment \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "automaticEnrollment": true
}
'

import requests

url = "https://api.getprimo.com/onboardings/{onboardingId}/equipment"

payload = { "automaticEnrollment": True }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({automaticEnrollment: true})
};

fetch('https://api.getprimo.com/onboardings/{onboardingId}/equipment', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.getprimo.com/onboardings/{onboardingId}/equipment",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'automaticEnrollment' => true
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getprimo.com/onboardings/{onboardingId}/equipment"

	payload := strings.NewReader("{\n  \"automaticEnrollment\": true\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.getprimo.com/onboardings/{onboardingId}/equipment")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"automaticEnrollment\": true\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getprimo.com/onboardings/{onboardingId}/equipment")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"automaticEnrollment\": true\n}"

response = http.request(request)
puts response.read_body

{
  "onboarding": {
    "id": "<string>",
    "status": "PENDING",
    "source": "COCKPIT",
    "createdAt": "2023-11-07T05:31:56Z",
    "hrRecords": [
      {
        "id": "<string>",
        "remoteId": "<string>",
        "firstName": "<string>",
        "lastName": "<string>",
        "email": "<string>",
        "personalEmail": "<string>",
        "phone": "<string>",
        "startDate": "2023-11-07T05:31:56Z",
        "terminationDate": "2023-11-07T05:31:56Z"
      }
    ],
    "emails": [
      "<string>"
    ],
    "employeeId": "<string>",
    "ticketId": "<string>",
    "stepModel": "ACTIONS",
    "stepProgress": {
      "done": 0,
      "total": 0
    },
    "startDate": "2023-11-07T05:31:56Z",
    "hire": {
      "firstName": "<string>",
      "lastName": "<string>",
      "emails": [
        "<string>"
      ],
      "agentNotes": [
        "<string>"
      ],
      "rawText": "<string>",
      "jobTitle": "<string>",
      "teamId": "<string>",
      "teamName": "<string>",
      "managerId": "<string>",
      "managerName": "<string>",
      "workLocationId": "<string>",
      "workLocationName": "<string>",
      "workMode": "REMOTE",
      "city": "<string>"
    }
  },
  "order": {
    "id": "<string>",
    "reference": "<string>",
    "status": "<string>"
  }
}

Get started

API Reference

Execute the equipment step of an onboarding

Authorizations

Path Parameters

Body

Response