> ## 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.

# Send hires and departures through the API

> Start onboardings and offboardings from your HR system's own automations when it can't connect through HR sync.

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](https://docs.getprimo.com/employees/set-up-hr-sync.md), 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.

> [!NOTE]
>
> 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](https://docs.getprimo.com/get-started/import-your-equipment.md#import-employees).

## Prerequisites

* A **Company API key** with **Read/write** access. See [Create API keys for Primo](https://docs.getprimo.com/api/create-primo-api-key.md).
* 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:

```bash theme={null}
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](https://docs.getprimo.com/employees/onboarding-agent.md) 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:

```bash theme={null}
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](https://docs.getprimo.com/employees/automated-offboardings.md). |

The cockpit finds the employee who holds that email address and starts the offboarding with your [offboarding settings](https://docs.getprimo.com/employees/offboarding-settings.md). 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](https://docs.getprimo.com/api/create-primo-api-key.md).

### Create the automation for hires

**1. Create the automation**

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

**2. 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.

**3. 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 |

**4. Map the payload to Rippling variables**

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

```json theme={null}
{
  "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

**1. Create the automation**

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

**2. Choose the trigger**

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

**3. 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:

```json theme={null}
{
  "email": "{{ work email }}",
  "terminationDate": "{{ termination date }}",
  "data": {
    "reason": "{{ termination reason }}",
    "manager": "{{ manager name }}"
  }
}
```

### Test and activate

**1. 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.

**2. 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](#handle-the-responses).

## Next steps

> [card] [Create API keys for Primo](https://docs.getprimo.com/api/create-primo-api-key.md)
>
> Generate a Primo API key to authenticate requests to the Primo REST API.

> [card] [Set up HR sync](https://docs.getprimo.com/employees/set-up-hr-sync.md)
>
> Connect your HR system to sync employee data automatically and let it drive
> onboardings, offboardings, and your employee directory.

> [card] [Onboarding Agent](https://docs.getprimo.com/employees/onboarding-agent.md)
>
> 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.