> For the complete documentation index, see [llms.txt](https://help.swarmia.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.swarmia.com/settings/integrations/hr-systems/personio.md).

# Personio

Connect Swarmia directly to Personio with an API credential to sync time off and match employees.

Swarmia connects directly to Personio with an API credential you create in Personio and paste into Swarmia. Once connected, Swarmia syncs time off and matches Personio employees to Swarmia authors.

## Requirements

* **Swarmia organization admin.** Connecting Personio requires the [organization admin role](/settings/organization/managing-users-and-roles.md) in Swarmia.
* **Personio admin.** Creating the API credential requires administrator access in Personio. The two steps can be done by different people: a Personio admin creates the credential, and a Swarmia organization admin pastes it in.
* **Email on every employee.** Swarmia matches Personio employees to Swarmia authors by email. Employees without an email won't sync, and their time off won't show up in Swarmia.

## Create the API credential in Personio

In Personio, an API credential is a **custom integration**. You create one, give it read access to employees and time off, and copy the credentials it generates.

1. In Personio, go to **Settings** → **Security & integrations** → **API credentials**. This opens **Marketplace** → **Connected integrations**.
2. Click **Create custom integration** and name it **Swarmia**.
3. Under **Configure access rights**, tick **Read** for **Employees** and for **Time Off**. Leave everything else unticked.
4. Under **Readable employee attributes**, select **Email**, **First name**, and **Last name**.
5. Leave **Readable legal entities** empty.
6. Finish the wizard. On **View credentials**, copy **Your client ID** and **Your API secret**.

{% hint style="warning" %}
**Personio shows the API secret only once.** Copy it before you leave the last step. The client ID stays visible on the integration's **API credentials** tab, but the secret never appears again. To get a new one, you have to reset the credential, which changes the client ID too.
{% endhint %}

{% hint style="warning" %}
**Leave Readable legal entities empty.** Selecting any legal entity limits the credential to people in those entities, and Personio doesn't report an error for anyone left out. Swarmia then sees only part of your organization and removes time off for everyone else. If people are missing time off in Swarmia, check this setting first.
{% endhint %}

{% hint style="info" %}
**Readable employee attributes are an allow-list, and omissions are silent.** Personio leaves out any attribute you haven't selected without reporting an error. Swarmia checks for **Email**, **First name**, and **Last name** when you connect, and tells you if any are missing.
{% endhint %}

## Connect Personio in Swarmia

1. Go to **Settings** → [**HR system**](https://app.swarmia.com/settings/hr-system).
2. In the Personio row, click **Connect**.
3. Paste the **Client ID** and **API secret**, then click **Connect**.

Swarmia validates the credential before saving it and stores the secret encrypted. The status flips to **Connected** and the initial sync starts in the background.

If Personio rejects the credential, Swarmia tells you what to fix:

* **The credential itself.** The client ID and API secret don't match, or the credential is no longer active in Personio.
* **Access rights.** The credential is missing **Read** access for **Employees** or **Time Off**.
* **Readable employee attributes.** The credential doesn't return **Email**, **First name**, or **Last name**.

Fix the credential in Personio and connect again.

## What Swarmia syncs

### Time off

* All time off from **2 years** before you connected to **1 month** ahead, refreshed every **24 hours**.
* Only **approved** time off counts. Pending and rejected absences don't, and an absence stops counting as soon as someone requests its deletion.
* **Deleted absences are removed.** When an absence is deleted in Personio, it disappears from Swarmia on the next refresh. Edited dates update the existing absence.
* **Part-day absences count as a full day.** A half day or a few hours off is stored as a whole day.
* **Offsite work doesn't count as time off.** Absence types categorized as offsite work in Personio, such as working from home, are treated as working days.
* **Open-ended absences don't sync** until an end date is set in Personio. They sync on the next daily refresh after you add one.

Apart from the offsite work category, Swarmia doesn't use the absence type. Vacation, sick leave, parental leave, and everything else are treated the same. Swarmia never reads balances, approvers, or comments on an absence.

### Employee data

* **Email and name only.** Swarmia uses them to match each Personio employee to a Swarmia author. They're read the first time an employee's time off syncs, so later changes in Personio don't carry over.

Swarmia doesn't read addresses, compensation, job details, employment status, org structure, or any other employee fields.

## Where the data shows up

* **Developer effort metrics** — approved time off reduces a person's available days, so effort scores reflect when people are actually working.
* **FTE counts** — feed into [investment balance](/features/focus/balance-engineering-investments.md) and [software capitalization](/features/capitalize-software-development-costs.md) reports.
* **Work log** — time off appears when work log is grouped by author.

See [Developer effort (FTEs)](/definitions/developer-effort-ftes.md) for how time off factors into the calculation.

## Check the connection status

The [HR system settings](https://app.swarmia.com/settings/hr-system) page shows the current status of the integration:

* **Connected** — the integration is healthy and syncing.
* **Disabled** — Personio stopped accepting the credential, so syncing has stopped.

If Personio rejects the credential during a sync, Swarmia waits an hour in case it's a temporary outage. If it's still rejected after that, Swarmia disables the integration and emails your Swarmia organization admins. The time off Swarmia already has stays as it is.

## Rotate the credential

1. In Personio, open the integration, go to the **API credentials** tab, and click **Reset Client ID & API Secret**.
2. In Swarmia, click **Reconnect** in the Personio card and paste the new client ID and API secret.

The new credential replaces the old one, and syncing continues. Reconnecting the same way also fixes a disabled integration.

{% hint style="info" %}
**Resetting changes the client ID as well as the secret.** Paste both. The old client ID stops working as soon as you reset.
{% endhint %}

To stop syncing, open the integration's overflow menu in Personio under **Marketplace** → **Connected integrations** and click **Disconnect integration**. Swarmia disables the integration, and the time off it already has stays as it is.

## Related

* [HR systems overview](/settings/integrations/hr-systems.md)
* [Upload time off data via CSV](/settings/integrations/hr-systems/upload-time-off-data-via-csv.md) — alternative when a direct integration isn't an option.
* [Time off API](/settings/integrations/swarmia-apis/time-off-api.md) — push time off into Swarmia programmatically.
* [Developer effort (FTEs)](/definitions/developer-effort-ftes.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.swarmia.com/settings/integrations/hr-systems/personio.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.