Send hires and departures through the API

Some HR systems don’t allow a third-party connection to read their data. Rippling, for example, only lets App Shop partners use its API. When your HR system can’t connect through HR sync, let it tell Primo about each hire and each departure instead: an automation in your HR system calls the Primo API, and the cockpit starts the onboarding or the offboarding.

These endpoints start one onboarding or one offboarding per call. They don’t sync your employee directory. To import the employees you already have, see Import employees.

Prerequisites

A Company API key with Read/write access. See Create API keys for Primo.
An HR system that can send an HTTP request when someone is hired or leaves: an automation, a workflow, or a webhook with a custom body and headers.

Start an onboarding

Send a POST request when someone is hired:

curl -X POST https://api.getprimo.com/employee-onboardings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Léa",
    "lastName": "Martin",
    "email": "lea.martin@acme.com",
    "startDate": "2026-11-24",
    "data": {
      "jobTitle": "Product Designer",
      "team": "Design",
      "manager": "Paul Durand",
      "workLocation": "Paris"
    }
  }'

Field	Required	Description
`firstName`	✅	First name of the hire
`lastName`	✅	Last name of the hire
`email`	✅	Work email of the hire
`startDate`		First day, as `YYYY-MM-DD` or an ISO 8601 date-time. Send it: the classic onboarding needs it.
`data`		Free JSON object with everything else your HR system knows (job title, team, manager, location, contract). At most 20,000 characters once serialized.

The cockpit starts the same onboarding an admin starts by hand for a hire who isn’t an employee yet. It creates the onboarding ticket and its steps, or hands the onboarding to the Onboarding Agent when it runs your onboardings. The agent reads data to fill in what the four fields don’t say.

Start an offboarding

Send a POST request when someone leaves:

curl -X POST https://api.getprimo.com/employee-offboardings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "lea.martin@acme.com",
    "terminationDate": "2026-12-15",
    "data": {
      "reason": "Resignation",
      "manager": "Paul Durand"
    }
  }'

Field	Required	Description
`email`	✅	An email address of the employee, as the cockpit knows it
`terminationDate`		Last day, as `YYYY-MM-DD` or an ISO 8601 date-time. Defaults to the last day already on the employee.
`data`		Free JSON object with what the record doesn’t say (reason, equipment to collect, who takes over). At most 5,000 characters once serialized. Saved as the offboarding’s notes for the Offboarding Agent.

The cockpit finds the employee who holds that email address and starts the offboarding with your offboarding settings. A hidden employee isn’t matched.

Handle the responses

Both endpoints answer 201 with the onboarding or the offboarding they created. A refusal carries an errorCode your automation can branch on:

Status	`errorCode`	What it means
`401` / `403`		The API key is missing, wrong, expired, or read-only. Use a Read/write key.
`404`	`EMPLOYEE_NOT_FOUND`	Offboarding only: no employee holds this email address.
`409`	`DUPLICATE_ONBOARDING`	An open onboarding already has this email address, or the same name and start date. Nothing was created, so a repeated call is safe.
`409`	`SEVERAL_EMPLOYEES_WITH_EMAIL`	Offboarding only: several employees hold this email address. Start the offboarding from the cockpit.
`409`	`OFFBOARDING_ALREADY_EXISTS`	The employee’s offboarding has already started.
`502` / `503`		Nothing was created. Call again.

Set it up in Rippling

Rippling’s Automation Studio calls the Primo API with its Call a public API step: one automation for hires, one for departures. Share this section with your Rippling admin.

Before you start

Your Rippling plan includes Automation Studio and its Call a public API step. Rippling documents this step for the Platform Pro subscription: check with your Rippling account manager if you don’t see it.
You are a Rippling super admin or full admin, or you have the Automation Studio permission.
You have a Primo Company API key with Read/write access. See Create API keys for Primo.

Create the automation for hires

Create the automation

In Rippling, go to Tools > Automation Studio and click Create automation. Name it, for example Primo – start onboarding.

Choose the trigger

Click Choose your automation trigger and pick the hire event your team uses: for example the new hire accepting their offer under When something happens, or Relative to start date (for example 14 days before the first day). Event names can differ slightly in your Rippling account: pick the closest one.

Add a Call a public API step

Click + Add a step > Call a public API, then fill in the step:

Field	Value
URL	`https://api.getprimo.com/employee-onboardings`
HTTP method	`POST`
Custom headers	`Authorization: Bearer YOUR_API_KEY` and `Content-Type: application/json`
Payload	The JSON below, in the Advanced tab

Map the payload to Rippling variables

Replace each placeholder with a Rippling variable, inserted with the lightning bolt icon:

{
  "firstName": "{{ first name }}",
  "lastName": "{{ last name }}",
  "email": "{{ work email }}",
  "startDate": "{{ start date }}",
  "data": {
    "jobTitle": "{{ title }}",
    "department": "{{ department }}",
    "manager": "{{ manager name }}",
    "workLocation": "{{ work location }}",
    "employmentType": "{{ employment type }}"
  }
}

Add or remove any field in data: the Onboarding Agent reads all of it.

Create the automation for departures

Create the automation

Create a second automation, for example Primo – start offboarding.

Choose the trigger

Under When something happens, pick the termination event, for example Termination request is submitted or its approval.

Add a Call a public API step

Use the URL https://api.getprimo.com/employee-offboardings, the POST method, and the same headers as for hires. Map the payload:

{
  "email": "{{ work email }}",
  "terminationDate": "{{ termination date }}",
  "data": {
    "reason": "{{ termination reason }}",
    "manager": "{{ manager name }}"
  }
}

Test and activate

Test each step

Click Test step with a test employee. The test sends a real request: a 201 response means the cockpit created the onboarding or the offboarding. Find it under Onboardings or Offboardings, then ignore it.

Publish and activate

Click Save, publish the automation, and turn on Activate this automation. An automation runs only once it is both published and activated.

Each automation lists its runs in its Execution history tab. A run fails when Primo answers an error or doesn’t answer within 60 seconds: match the status code with Handle the responses.

Next steps

Create API keys for Primo

Generate a Primo API key to authenticate requests to the Primo REST API.

Set up HR sync

Connect your HR system to sync employee data automatically and let it drive onboardings, offboardings, and your employee directory.

Onboarding Agent

Let Primo AI run every new onboarding from instructions you write: it builds the ticket and its tasks, works with the new hire by email, and hands your team what it can’t do.

Welcome to Primo

Platform configuration

Onboardings & Offboardings

AI Agents

Helpdesk

Device Management

Endpoint Protection

SaaS Management

Global Purchasing

Send hires and departures through the API

Prerequisites

Start an onboarding

Start an offboarding

Handle the responses

Set it up in Rippling

Before you start

Create the automation for hires

Create the automation for departures

Test and activate

Next steps

Create API keys for Primo

Set up HR sync

Onboarding Agent

​Prerequisites

​Start an onboarding

​Start an offboarding

​Handle the responses

​Set it up in Rippling

​Before you start

​Create the automation for hires

​Create the automation for departures

​Test and activate

​Next steps

Create API keys for Primo

Set up HR sync

Onboarding Agent

Prerequisites

Start an onboarding

Start an offboarding

Handle the responses

Set it up in Rippling

Before you start

Create the automation for hires

Create the automation for departures

Test and activate

Next steps