Onboardings

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.

POST

onboardings

curl --request POST \
  --url https://api.getprimo.com/onboardings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "employeeId": "<string>",
  "startDate": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://api.getprimo.com/onboardings"

payload = {
    "employeeId": "<string>",
    "startDate": "2023-11-07T05:31:56Z"
}
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({employeeId: '<string>', startDate: '2023-11-07T05:31:56Z'})
};

fetch('https://api.getprimo.com/onboardings', 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",
  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([
    'employeeId' => '<string>',
    'startDate' => '2023-11-07T05:31:56Z'
  ]),
  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"

	payload := strings.NewReader("{\n  \"employeeId\": \"<string>\",\n  \"startDate\": \"2023-11-07T05:31:56Z\"\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")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"employeeId\": \"<string>\",\n  \"startDate\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getprimo.com/onboardings")

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  \"employeeId\": \"<string>\",\n  \"startDate\": \"2023-11-07T05:31:56Z\"\n}"

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

{
  "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>"
  }
}

Key: Write Scope: Company

Authorizations

Authorization

string

header

required

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

Body

application/json

employeeId

string

required

Primo employee id of the joiner. Get it from getEmployees or createEmployee.

Pattern: ^[a-f\d]{24}$

startDate

string<date-time> | null

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.

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))$

Response

default - application/json

string

required

status

enum<string>

required

Available options:

PENDING,

SCHEDULED,

IN_PROGRESS,

CLOSED,

CANCELED

source

enum<string>

required

Available options:

COCKPIT,

MERGE,

KOMBO,

API

createdAt

string<date-time>

required

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

object[]

required

HR records from the connected HRIS (Kombo) for this onboarding

Show child attributes

emails

string[]

required

Every email address of the employee being onboarded. Empty while the onboarding has no employee.

employeeId

string | null

ticketId

string | null

stepModel

enum<string> | null

How the onboarding holds its steps: ACTIONS (the onboarding steps and their plain tasks) or INTENTS (typed tasks under its ticket, run through the intent tools such as executeEmployeeCreationIntent). Null while it has neither a ticket nor a step, and for an onboarding run by the agent.

Available options:

ACTIONS,

INTENTS

stepProgress

object | null

How many of its steps are through, out of how many: on ACTIONS its steps done, scheduled or skipped; otherwise the typed tasks of its ticket completed or cancelled. Null while it has no step.

Show child attributes

startDate

string<date-time> | null

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))$

hire

object | null

The hire an admin added by hand in the cockpit short form, before they are an employee in Primo

Show child attributes

Create an onboarding for an existing employee

curl --request POST \
  --url https://api.getprimo.com/onboardings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "employeeId": "<string>",
  "startDate": "2023-11-07T05:31:56Z"
}
'

import requests

url = "https://api.getprimo.com/onboardings"

payload = {
    "employeeId": "<string>",
    "startDate": "2023-11-07T05:31:56Z"
}
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({employeeId: '<string>', startDate: '2023-11-07T05:31:56Z'})
};

fetch('https://api.getprimo.com/onboardings', 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",
  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([
    'employeeId' => '<string>',
    'startDate' => '2023-11-07T05:31:56Z'
  ]),
  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"

	payload := strings.NewReader("{\n  \"employeeId\": \"<string>\",\n  \"startDate\": \"2023-11-07T05:31:56Z\"\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")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"employeeId\": \"<string>\",\n  \"startDate\": \"2023-11-07T05:31:56Z\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getprimo.com/onboardings")

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  \"employeeId\": \"<string>\",\n  \"startDate\": \"2023-11-07T05:31:56Z\"\n}"

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

{
  "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>"
  }
}

Get started

API Reference

Create an onboarding for an existing employee

Authorizations

Body

Response