# Personio

Create and update employees, record absences and working time, manage projects, and upload or download employee documents in Personio.

## Connect Personio

1. In the sidebar, open **Connections** and press **Add connection**.
2. Type `personio` and choose **Personio**.
3. Fill in the fields. Each one says **Required** or **Optional**.
4. Press **Test and save**. GoRunner checks the connection before it saves anything.

The sheet asks for:

- **Client ID · Required**: The API credential’s client ID (papi-…).
- **Client secret · Required**: The API credential’s client secret, shown once when the credential is created.

[Connections](https://docs.gorunner.io/build/connections) says how to sign in again, rename or delete it. In a product that embeds GoRunner, **Add connection** can be missing: then [your provider makes connections](https://docs.gorunner.io/embed/customer-connections) for you.

## Start a workflow

Add a trigger and choose **Personio**. The trigger uses the same connection as the steps.

### On Employee or Absence Change

Checks Personio about once a minute and starts a run for each employee or absence added (or changed) since the check before. The first check after publishing only takes note of the time (it starts nothing); changing the trigger starts over the same way. Each change starts one run, at most 100 a minute (the rest follow the minute after).

- **Trigger on · Required**: What starts a run. Options: Employee added, Employee added or changed, Absence requested, Absence requested or changed. Default: Employee added.
- **Absence Type · Optional**: Only absences of this type (empty: every type). Shows when **Trigger on** is **Absence requested** or **Absence requested or changed**.
- **Only Awaiting Approval · Optional**: Only absences whose approval is still pending. Off by default. Shows when **Trigger on** is **Absence requested** or **Absence requested or changed**.

A later step can use its data, such as `{{trigger.approval}}`, `{{trigger.change_type}}`, `{{trigger.created_at}}` and 6 more. See [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Do things in Personio

Add a **Personio** step, choose a **Resource**, then an **Operation**. Choose a row to see its fields.

- [Employee](https://docs.gorunner.io/apps/personio#fields-f-person): Create · Get · Get Many · Update · Delete
- [Employment](https://docs.gorunner.io/apps/personio#fields-f-employment): Get · Get Many · Update
- [Absence](https://docs.gorunner.io/apps/personio#fields-f-absence): Create · Get · Get Many · Update · Delete
- [Absence Type](https://docs.gorunner.io/apps/personio#fields-f-absencetype): Get · Get Many
- [Attendance](https://docs.gorunner.io/apps/personio#fields-f-attendance): Create · Get · Get Many · Update · Delete
- [Project](https://docs.gorunner.io/apps/personio#fields-f-project): Create · Get · Get Many · Update · Delete
- [Document](https://docs.gorunner.io/apps/personio#fields-f-document): Upload · Get Many · Download · Update · Delete

Later steps read a step’s output by its name: see [Use data from earlier steps](https://docs.gorunner.io/build/use-data-from-earlier-steps).

## Limits

- A reply from Personio can be up to 16 MB (a file download can have its own limit). A larger one fails the step; it is never cut short.
- When Personio says to slow down (429), the step waits as long as it asks, if the step’s time allows. Otherwise it fails and says when to try again.

Not in your list? See [When an app isn’t here](https://docs.gorunner.io/apps/when-an-app-isnt-here#q-not-in-list).

## For developers

In the API, which calls apps pieces, Personio is `pieceId: "personio"` with `actionId: "personio"`, set by `resource` and an `operation_…` field, such as `operation_absence`. Its trigger is `personiotrigger` / `personio_poll`. [Get an app](https://docs.gorunner.io/api/apps/get-app) returns every field.

It can change something outside the run (`writes_external`). See [How versions and side effects work](https://docs.gorunner.io/apps#q-versions).

### Personio › Employee

### Create

- **First Name · Optional**: The employee's first name.
- **Last Name · Optional**: The employee's last name.
- **Email · Optional**: The employee's work email; unique across employees.
- **Preferred Name · Optional**: The name the employee goes by.
- **Gender · Optional**: The employee's gender. Options: Not set, Male, Female, Diverse, Unknown. Default: Not set.
- **Language · Optional**: The language Personio uses with the employee. Options: Not set, German, English, Spanish, French, Italian, Dutch, Swedish, Finnish. Default: Not set.
- **Custom Attributes · Optional**: Attribute values by attribute id, such as {"dynamic_1234": "Sales", "dynamic_5678": ["Munich", "Berlin"]}.
- **Employment Status · Optional**: The status of the employee's employment. Options: Active, Onboarding, Inactive, On leave. Default: Active.
- **Start Date · Optional**: The first day of the employment (YYYY-MM-DD).
- **Employment Type · Optional**: Internal (on the payroll) or external. Options: Internal, External. Default: Internal.
- **Position · Optional**: The employee's job title.
- **Supervisor · Optional**: The Personio id of the employee's supervisor.
- **Weekly Working Hours · Optional**: Contracted hours a week (up to two decimals).
- **More Employment Fields · Optional**: Other employment fields as Personio names them, such as {"office": {"id": "123"}, "legal_entity": {"id": "45"}, "probation_end_date": "2027-04-30"}.

### Get and Delete

- **Employee · Required**: The employee to read, change or delete.

### Get Many

- **Email · Optional**: Only the employee with this email (several, comma-separated).
- **First Name · Optional**: Only employees with exactly this first name.
- **Last Name · Optional**: Only employees with exactly this last name.
- **Status · Optional**: Only active or only inactive employees. Options: Any, Active, Inactive. Default: Any.
- **Updated After · Optional**: Only employees changed after this time (2026-11-01 or 2026-11-01T09:00:00Z).
- **Created After · Optional**: Only employees added after this time.
- **Return All · Optional**: Read every employee, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many employees to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **First Name · Optional**: The employee's first name.
- **Employee · Required**: The employee to read, change or delete.
- **Last Name · Optional**: The employee's last name.
- **Email · Optional**: The employee's work email; unique across employees.
- **Preferred Name · Optional**: The name the employee goes by.
- **Gender · Optional**: The employee's gender. Options: Not set, Male, Female, Diverse, Unknown. Default: Not set.
- **Language · Optional**: The language Personio uses with the employee. Options: Not set, German, English, Spanish, French, Italian, Dutch, Swedish, Finnish. Default: Not set.
- **Custom Attributes · Optional**: Attribute values by attribute id, such as {"dynamic_1234": "Sales", "dynamic_5678": ["Munich", "Berlin"]}.

### Personio › Employment

### Get

- **Employee · Required**: The employee the employment belongs to.
- **Employment · Required**: The employment's Personio id (a person's employments list shows it).

### Get Many

- **Employee · Required**: The employee the employment belongs to.
- **Return All · Optional**: Read every employment, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many employments to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Employee · Required**: The employee the employment belongs to.
- **Employment · Required**: The employment's Personio id (a person's employments list shows it).
- **Changes · Required**: The employment fields to set, as Personio names them, such as {"position": {"title": "Team Lead"}, "weekly_working_hours": 32, "supervisor": {"id": "1234"}}.

### Personio › Absence

### Create

- **Employee · Required**: The employee who is absent.
- **Absence Type · Required**: The kind of absence (vacation, sick leave, …).
- **Start · Optional**: The first day (or moment) of the absence, as a local date and time without a time zone (2026-11-03T09:00:00); a date alone is its midnight. Personio reads it in the employee's time zone.
- **Start Half · Optional**: For a day-based absence type: the whole first day, or only its first or second half. Options: Whole day, First half, Second half. Default: Whole day.
- **End · Optional**: The last day (or moment) of the absence, empty for an open end (long sick leave), as a local date and time without a time zone (2026-11-03T09:00:00); a date alone is its midnight. Personio reads it in the employee's time zone.
- **End Half · Optional**: For a day-based absence type: the whole last day, or only its first or second half. Options: Whole day, First half, Second half. Default: Whole day.
- **Comment · Optional**: A note on the absence (at most 2,000 characters).
- **Substitute · Optional**: The Personio id of the employee who stands in (only where the absence type allows substitutes).
- **Skip Approval · Optional**: Record it as approved, skipping the approval Personio would otherwise ask for. Off by default.

### Get and Delete

- **Absence · Required**: The absence period's Personio id.

### Get Many

- **Employees · Optional**: Only absences of these employees (Personio ids, comma-separated).
- **Absence Types · Optional**: Only absences of these types (ids, comma-separated).
- **Starting On or After · Optional**: Only absences that start at or after this local date or time.
- **Starting On or Before · Optional**: Only absences that start at or before this local date or time.
- **Updated After · Optional**: Only absences changed at or after this time (2026-11-01 or 2026-11-01T09:00:00Z).
- **Return All · Optional**: Read every absence, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many absences to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Absence · Required**: The absence period's Personio id.
- **Start · Optional**: The first day (or moment) of the absence, as a local date and time without a time zone (2026-11-03T09:00:00); a date alone is its midnight. Personio reads it in the employee's time zone.
- **Start Half · Optional**: For a day-based absence type: the whole first day, or only its first or second half. Options: Whole day, First half, Second half. Default: Whole day.
- **End · Optional**: The last day (or moment) of the absence, empty for an open end (long sick leave), as a local date and time without a time zone (2026-11-03T09:00:00); a date alone is its midnight. Personio reads it in the employee's time zone.
- **End Half · Optional**: For a day-based absence type: the whole last day, or only its first or second half. Options: Whole day, First half, Second half. Default: Whole day.
- **Comment · Optional**: A note on the absence (at most 2,000 characters).
- **Skip Approval · Optional**: Record it as approved, skipping the approval Personio would otherwise ask for. Off by default.

### Personio › Absence Type

### Get

- **Absence Type · Required**: The absence type to read.

### Get Many

- **Return All · Optional**: Read every absence type, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many absence types to return (1–2000). Default: 100. Shows when **Return All** is off.

### Personio › Attendance

### Create

- **Employee · Required**: The employee whose time this is.
- **Type · Optional**: Working time or a break. Options: Work, Break. Default: Work.
- **Start · Optional**: When the period starts, as a local date and time without a time zone (2026-11-03T09:00:00); a date alone is its midnight. Personio reads it in the employee's time zone.
- **End · Optional**: When it ends, empty while it is still running, as a local date and time without a time zone (2026-11-03T09:00:00); a date alone is its midnight. Personio reads it in the employee's time zone. A period lasts at most 24 hours.
- **Project · Optional**: The project the time counts toward (an active project; not on a break).
- **Comment · Optional**: A note on the period (at most 1,000 characters).
- **Skip Approval · Optional**: Record it as approved, skipping the approval Personio would otherwise ask for. Off by default.

### Get and Delete

- **Attendance · Required**: The attendance period's Personio id.

### Get Many

- **Employees · Optional**: Only periods of these employees (Personio ids, comma-separated).
- **Projects · Optional**: Only periods on these projects (ids, comma-separated).
- **Approval · Optional**: Only periods with this approval status. Options: Any, Pending, Confirmed, Rejected. Default: Any.
- **Starting On or After · Optional**: Only periods that start at or after this local date or time.
- **Starting On or Before · Optional**: Only periods that start at or before this local date or time.
- **Updated After · Optional**: Only periods changed at or after this time (2026-11-01 or 2026-11-01T09:00:00Z).
- **Return All · Optional**: Read every attendance period, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many attendance periods to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Attendance · Required**: The attendance period's Personio id.
- **Start · Optional**: When the period starts, as a local date and time without a time zone (2026-11-03T09:00:00); a date alone is its midnight. Personio reads it in the employee's time zone.
- **End · Optional**: When it ends, empty while it is still running, as a local date and time without a time zone (2026-11-03T09:00:00); a date alone is its midnight. Personio reads it in the employee's time zone. A period lasts at most 24 hours.
- **Project · Optional**: The project the time counts toward (an active project; not on a break).
- **Comment · Optional**: A note on the period (at most 1,000 characters).
- **Skip Approval · Optional**: Record it as approved, skipping the approval Personio would otherwise ask for. Off by default.

### Personio › Project

### Create

- **Name · Optional**: The project's name (unique, at most 255 characters).
- **Status · Optional**: Active projects take time entries; archived ones do not. Options: Leave as it is (new: Active), Active, Archived. Default: Leave as it is (new: Active).
- **Project Code · Optional**: A unique code for the project.
- **Description · Optional**: What the project is (at most 1,000 characters).
- **Client · Optional**: The client the project is for.
- **Project Type · Optional**: A type of your own (such as Internal, Customer).
- **Billable · Optional**: Whether time on the project is billed. Options: Leave as it is, Yes, No. Default: Leave as it is.
- **Start Date · Optional**: The project's first day (YYYY-MM-DD).
- **End Date · Optional**: The day after the project's last day (YYYY-MM-DD; Personio's end is exclusive).
- **Cost Center · Optional**: The Personio id of the project's cost center.
- **Parent Project · Optional**: Make it a sub-project of this project.
- **Open to Everyone · Optional**: Let every employee track time to it (removes its member list). Options: Leave as it is, Yes, No. Default: Leave as it is.

### Get and Delete

- **Project · Required**: The project to read, change or delete.

### Get Many

- **Name · Optional**: Only projects with exactly this name (several, comma-separated).
- **Status · Optional**: Only active or only archived projects. Options: Any, Active, Archived. Default: Any.
- **Top-Level Only · Optional**: Leave out sub-projects. Off by default.
- **Return All · Optional**: Read every project, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many projects to return (1–2000). Default: 50. Shows when **Return All** is off.

### Update

- **Project · Required**: The project to read, change or delete.
- **Name · Optional**: The project's name (unique, at most 255 characters).
- **Status · Optional**: Active projects take time entries; archived ones do not. Options: Leave as it is (new: Active), Active, Archived. Default: Leave as it is (new: Active).
- **Project Code · Optional**: A unique code for the project.
- **Description · Optional**: What the project is (at most 1,000 characters).
- **Client · Optional**: The client the project is for.
- **Project Type · Optional**: A type of your own (such as Internal, Customer).
- **Billable · Optional**: Whether time on the project is billed. Options: Leave as it is, Yes, No. Default: Leave as it is.
- **Start Date · Optional**: The project's first day (YYYY-MM-DD).
- **End Date · Optional**: The day after the project's last day (YYYY-MM-DD; Personio's end is exclusive).
- **Cost Center · Optional**: The Personio id of the project's cost center.
- **Open to Everyone · Optional**: Let every employee track time to it (removes its member list). Options: Leave as it is, Yes, No. Default: Leave as it is.

### Personio › Document

### Upload

- **Employee · Required**: The employee the document belongs to.
- **Category · Optional**: The document category (Personio › Settings › Documents).
- **File · Required**: Upload a file, or switch to an expression to use one from an earlier step (such as {{steps.download.result}}). At most 30 MB; PDF, Office documents and images are accepted.
- **Title · Optional**: The document's name in Personio (at most 255 characters). Empty uses the file name.
- **Comment · Optional**: A note on the document.
- **Date · Optional**: The date Personio sorts the document by (YYYY-MM-DD).

### Get Many

- **Employee · Required**: The employee the document belongs to.
- **Category · Optional**: Only documents in this category (its id).
- **Created On or After · Optional**: Only documents created on or after this date (YYYY-MM-DD).
- **Return All · Optional**: Read every document, page by page (at most 2000; past that the step fails rather than stop early). Off by default.
- **Limit · Optional**: How many documents to return (1–2000). Default: 50. Shows when **Return All** is off.

### Download and Delete

- **Document · Required**: The document's Personio id (Get Many lists it).

### Update

- **Document · Required**: The document's Personio id (Get Many lists it).
- **Category · Optional**: The document category (Personio › Settings › Documents).
- **Title · Optional**: The document's name in Personio (at most 255 characters). Empty uses the file name.
- **Comment · Optional**: A note on the document.
- **Date · Optional**: The date Personio sorts the document by (YYYY-MM-DD).

Source: https://docs.gorunner.io/apps/personio