# Personio — HRIS API: connection

> Canonical URL: https://developers.apideck.com/apis/hris/personio/connection

# How to connect to Personio

Personio connections use API credentials that you generate inside your own Personio account. There is no consent screen to approve and nothing to register with Personio in advance: an administrator in your Personio account creates a credential pair (a **Client ID** and a **Client Secret**), decides what that credential is allowed to read and write, and you paste the pair into Apideck Vault. Apideck exchanges those credentials for a short-lived access token on every connection and refreshes it for you.

Plan the access levels and employee attributes before you generate the credential (steps 4 and 5). Those two choices decide what the integration can actually see, and getting them right up front saves a round of reconnecting later.

## Prerequisites

- A Personio account on a plan that includes API access (**Core Pro** at the time of writing). If **API credentials** does not appear under Settings, your plan or your role is the reason: your Personio contact can confirm which applies.
- **Administrator** access in Personio. Only an administrator can reach Settings > Integrations > API credentials and set a credential's access levels and readable employee attributes.
- A note of which resources your integration needs. This connector reads and writes employees, and reads time-off requests.

## 1. Log in to Personio

Go to your Personio [login page](https://app.personio.de/login), enter your email address and password, and click **Login**.

![Personio login screen](https://res.cloudinary.com/apideck/image/upload/v1670942404/docs/connectors/personio/personio-login.png)

## 2. Open the API credentials screen

In the sidebar, click **Settings**.

![Personio settings in the sidebar](https://res.cloudinary.com/apideck/image/upload/v1670942404/docs/connectors/personio/personio-settings.png)

Then go to **Integrations** and click **API credentials**.

![Personio API credentials overview](https://res.cloudinary.com/apideck/image/upload/v1670942404/docs/connectors/personio/personio-api-credentials.png)

## 3. Generate a new credential

Click **Generate new credential** at the top right. In the form that slides in:

- In the **Name** field, enter something you will recognise later, for example `Apideck integration`.
- In the **Integration** drop-down, select the relevant integration if it is listed. If it is not, select **Other**.

Personio pre-selects recommended access levels and attributes when you pick a listed integration. Treat those as a starting point and check them against steps 4 and 5 rather than accepting them unchanged.

## 4. Set the access levels

Use the checkboxes to grant the credential access per resource. For this connector:

- **Employees**: grant **Read**. Also grant **Write** if your integration creates or updates employees in Personio.
- The section covering absences and time off: grant **Read** if you need time-off requests.

Leave everything your integration does not use unchecked. A credential can only ever do what these boxes allow, so a resource left unchecked returns nothing rather than an obvious error.

## 5. Choose the readable employee attributes

When you select **Read** for Employees, a **Readable employee attributes** drop-down appears. Choose every employee attribute that should be transferred out of Personio.

![Personio readable employee attributes](https://res.cloudinary.com/apideck/image/upload/v1670941847/docs/connectors/personio/personio-employee-attributes.png)

This step is the one most worth slowing down for. Personio only sends the attributes you tick here, and it does so silently: an attribute you leave out arrives as empty rather than as an error, so a narrow selection looks like missing or incomplete data in your integration rather than like a permissions problem. Include the identity and employment fields your integration relies on (name, email, status, hire date, department, and so on) plus any custom attributes you map.

You can come back to this screen and widen the selection later without regenerating the credential.

## 6. Copy the Client ID and Client Secret

Click **Generate new credential** to create the pair.

![Personio generated API credentials](https://res.cloudinary.com/apideck/image/upload/v1670941848/docs/connectors/personio/personio-credentials.png)

Copy the **Client ID** and the **Client Secret** and store them somewhere secure. **They are shown only once.** If you lose the secret, you cannot read it back: return to this screen and generate a replacement credential (and reconnect in Vault with the new pair).

Personio documents this screen in more detail in [Generate and manage API credentials](https://support.personio.de/hc/en-us/articles/4404623630993-Generate-and-manage-API-credentials).

## 7. Enter the credentials in Apideck Vault

Open the Personio connection in Vault and fill in the two fields:

| Vault field | Value |
|---|---|
| **Client ID** | The Client ID from step 6 |
| **Client Secret** | The Client Secret from step 6 |

![Personio connection settings in Apideck Vault](https://res.cloudinary.com/apideck/image/upload/v1670941848/docs/connectors/personio/vault-personio.png)

Click **Save**. Apideck validates the pair against Personio straight away, so a typo shows up here rather than on your first API call. Once validated, the connection is ready to use.

## Notes

- **Access is scoped to the credential, not to the person who created it.** The access levels and readable attributes from steps 4 and 5 are the ceiling for everything the connection can do, whatever permissions the administrator holds.
- **Individual employees can be excluded from API transfer.** Personio supports a per-employee **Include in transfer** field. Where it is used, employees whose value excludes them are not shared over the API, so a record can be missing from the connection while existing normally in Personio. If an employee you expect is absent, check that field on their profile before treating it as a connector issue.
- **Revoking is immediate.** Deleting the credential in Personio stops the connection working at once. Generate a fresh credential and update the connection in Vault to restore it.
- **The same credential pair works for testing and production.** Personio does not issue separate keys per environment, so be deliberate about which Personio account you generate the credential in.

## Troubleshooting

| Issue | What to check |
|---|---|
| **API credentials** is missing under Settings > Integrations | Your role is not Administrator, or your Personio plan does not include API access. Your Personio contact can confirm which. |
| The connection fails to authenticate after saving | Re-copy both values. A secret is shown only once and is easy to truncate; if in doubt, generate a replacement credential and reconnect. |
| Employees come back with empty or missing fields | The attribute is not ticked in **Readable employee attributes** (step 5). Add it in Personio; no reconnection is needed. |
| Some employees never appear | Check the **Include in transfer** field on the missing profiles, then confirm **Employees: Read** is still granted on the credential. |
| Time-off requests are empty | The credential has no read access to absences and time off (step 4). |
| Creating or updating an employee is rejected | The credential has **Read** but not **Write** on Employees, or the field being written is not among the credential's attributes. |
| Requests start failing with HTTP 429 | Personio is rate-limiting the account. Back off and retry; sustained 429s usually mean another integration is sharing the same limit. |

Still stuck? Contact [Apideck Support](https://help.apideck.com/en/articles/7774658).


[API reference](https://developers.apideck.com/apis/hris/reference.md) · [Coverage matrix](https://developers.apideck.com/apis/hris/coverage)