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, enter your email address and password, and click Login.

2. Open the API credentials screen

In the sidebar, click Settings.

Then go to Integrations and click API credentials.

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.

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.

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.

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

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.