This article explains how to generate and manage credentials for Personio public APIs. APIs allow Personio to share data with other services or tools. API credentials act like a key that controls the flow of information and decides what gets shared.
Before you start
- To use the Marketplace and set up integrations, you need to have edit rights for Marketplace Integration and API.
- To create your own custom integration using our public API, you need the Core Pro Personio plan.
- Personio automatically creates API credentials for all integrations except custom ones.
Learn about API credentials
API credentials build connections and protect communication between applications. In Personio, the system creates API credentials for the following:
- Recruiting API
- Integrations from Personio
- Integrations from Personio partners
You can't manage these credentials yourself. You can update these integrations through the Personio Marketplace. The system sets most API permissions to the level needed for the integration to work. You usually generate and manage API credentials manually for custom integrations.
How API access works for custom integrations
When you set up a custom integration, you define its Access rights (for example, whether it can read or write data in areas like Employees, Attendances, Time off, and Documents). The integration then uses its API credentials (Client ID and API secret) to authenticate API requests.
API access works differently from employee role-based access in Personio. Employee role permissions control what users can see and do in the Personio interface, but they don't control what custom integrations can retrieve via the API. This means you cannot limit API access to only the employees in a specific role using employee role permissions.
Generate API credentials for custom integrations
To generate credentials for custom integrations:
- Go to Marketplace > Connected Integrations.
- Click Create custom integration at the top right of the screen. This button is only available if you have the Core Pro Personio plan. If you cannot see it, check your current plan to confirm you're on Core Pro.
- Configure the setup.
Note:
Write permissions do not include read access. If you want to retrieve data via our APIs, you also need to grant Read permissions.
The following table shows what each permission allows a third-party system to do. Some permissions are available for read access only. For endpoint details, visit the Developer Hub.
Integration permissions |
Read permissions | Write permissions |
|---|---|---|
Employees |
Allow third-party systems to pull data from Personio. | Allow third-party systems to create and update data in Personio. |
Attendances |
Allow third-party systems to pull data from Personio. | Allow third-party systems to create, update, and delete data in Personio. |
Time off |
Allow third-party systems to pull data from Personio. | Allow third-party systems to create and update data in Personio. |
Documents |
Allow third-party systems to pull document category IDs from Personio. | Allow third-party systems to create documents in Personio. |
Custom Reports |
Allow third-party systems to retrieve all existing custom reports from Personio. Check this box to make all attributes in a custom report retrievable. This applies even if they don't appear under Readable employee attributes. |
Not applicable. |
Recruiting |
Allow third-party systems to pull data from Personio. | Allow third-party systems to create and update data in Personio. |
Webhooks |
Retrieve webhook meta information. |
Create, update, and delete webhooks. Read and Write permissions don't affect whether a webhook triggers. A webhook keeps working after you create it, no matter the permission settings. Learn more about webhooks in our technical documentation. |
Org Units |
Allow third-party systems to pull data from Personio. | Not applicable. |
Legal Entities |
Allow third-party systems to pull data from Personio. | Not applicable. |
Cost Centers |
Allow third-party systems to pull data from Personio. | Not applicable. |
Workplaces |
Allow third-party systems to pull data from Personio. | Not applicable. |
Reports |
Allow third-party systems to pull data from Personio. | Not applicable. |
Update API credentials for custom integrations
To update the permissions for custom integrations:
- Go to Marketplace > Connected integrations.
- Click the integration to update.
- In the window that appears, make your changes.
- Save your settings.
You can also reset the API credentials from here by following the instructions.
Disconnect or disable API credentials for custom integrations
To disconnect or disable API credentials for custom integrations:
- Go to Marketplace > Connected integrations.
- In the Action column, click the three dots.
- Click Disable to temporarily disable credentials.
- Click Disconnect to permanently delete credentials.
Access technical documentation
Find all API documentation in our Developer Hub. This includes endpoints, webhooks, data details, and tutorials. The Developer Hub has two versions with different content. Webhook information is in version 2.0. To switch versions, click the version number at the top of the home page.