Onboardings

Create the onboarding of a joiner from an HR system event

Start the onboarding of a joiner who is not an employee in Primo yet, from what an HR system or an automation knows: first name, last name, work email, the start date, and a free data object with everything else. Primo starts the whole flow, the way an admin does from the cockpit short form: the onboarding ticket and its steps, or the Onboarding Agent when it runs the onboardings of the company. data is kept on the onboarding as the hire text the agent reads. Refused with 409 DUPLICATE_ONBOARDING when an open onboarding already has this email, or the same name and start date, so a repeated call creates nothing; 502 FAIL_TO_CREATE_ONBOARDING_TICKET and 503 ONBOARDING_AGENT_STATUS_UNAVAILABLE created nothing, call again. For an employee who already exists in Primo, use createOnboarding with their id instead.

POST

employee-onboardings

curl --request POST \
  --url https://api.getprimo.com/employee-onboardings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "<string>",
  "lastName": "<string>",
  "email": "jsmith@example.com",
  "startDate": "2023-12-25",
  "data": {}
}
'

import requests

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

payload = {
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "jsmith@example.com",
    "startDate": "2023-12-25",
    "data": {}
}
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({
    firstName: '<string>',
    lastName: '<string>',
    email: 'jsmith@example.com',
    startDate: '2023-12-25',
    data: {}
  })
};

fetch('https://api.getprimo.com/employee-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/employee-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([
    'firstName' => '<string>',
    'lastName' => '<string>',
    'email' => 'jsmith@example.com',
    'startDate' => '2023-12-25',
    'data' => [
        
    ]
  ]),
  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/employee-onboardings"

	payload := strings.NewReader("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"jsmith@example.com\",\n  \"startDate\": \"2023-12-25\",\n  \"data\": {}\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/employee-onboardings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"jsmith@example.com\",\n  \"startDate\": \"2023-12-25\",\n  \"data\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getprimo.com/employee-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  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"jsmith@example.com\",\n  \"startDate\": \"2023-12-25\",\n  \"data\": {}\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

firstName

string

required

First name of the joiner

Minimum string length: 1

lastName

string

required

Last name of the joiner

Minimum string length: 1

string<email>

required

Work email of the joiner

Pattern: ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$

startDate

First day of the joiner (YYYY-MM-DD or ISO 8601). Required by the classic onboarding, read by the agent.

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

data

object | null

Everything else the caller knows about the joiner, as a free JSON object (job title, team, manager, location, contract…), at most 20000 characters once serialized. Kept on the onboarding and read by the Onboarding Agent. May hold personal data.

Show child attributes

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 the onboarding of a joiner from an HR system event

curl --request POST \
  --url https://api.getprimo.com/employee-onboardings \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "firstName": "<string>",
  "lastName": "<string>",
  "email": "jsmith@example.com",
  "startDate": "2023-12-25",
  "data": {}
}
'

import requests

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

payload = {
    "firstName": "<string>",
    "lastName": "<string>",
    "email": "jsmith@example.com",
    "startDate": "2023-12-25",
    "data": {}
}
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({
    firstName: '<string>',
    lastName: '<string>',
    email: 'jsmith@example.com',
    startDate: '2023-12-25',
    data: {}
  })
};

fetch('https://api.getprimo.com/employee-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/employee-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([
    'firstName' => '<string>',
    'lastName' => '<string>',
    'email' => 'jsmith@example.com',
    'startDate' => '2023-12-25',
    'data' => [
        
    ]
  ]),
  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/employee-onboardings"

	payload := strings.NewReader("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"jsmith@example.com\",\n  \"startDate\": \"2023-12-25\",\n  \"data\": {}\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/employee-onboardings")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"jsmith@example.com\",\n  \"startDate\": \"2023-12-25\",\n  \"data\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.getprimo.com/employee-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  \"firstName\": \"<string>\",\n  \"lastName\": \"<string>\",\n  \"email\": \"jsmith@example.com\",\n  \"startDate\": \"2023-12-25\",\n  \"data\": {}\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 the onboarding of a joiner from an HR system event

Authorizations

Body

Response