This article explains how to generate and manage (update, disable, re-enable and remove) credentials for the Personio Personnel Data APIs and the Personio Custom Reports API.

The credentials for our Recruiting API are system-generated and are not managed by administrators.

What are API credentials in Personio?

API credentials allow data to be exchanged between Personio and another service or tool. This way, you can build connections between Personio and your own system, or set up integrations with third-party providers that are available in the Personio Marketplace. You need to enter API credentials when activating an integration.

Note
API credentials help to safeguard the communication between applications and avoid unauthorized access, which can lead to data breaches. For data security reasons, it is recommended that you generate new API credentials for each integration.

Generate API credentials

1. Go to Settings > Integrations > API credentials.
2. Click Generate new credential on the top right of the screen.
3. The Add new credential sidebar will appear. In the Name field, enter a meaningful name (for example, 'Greenhouse integration' or 'Custom Reports') for the credentials.
4. If applicable, select the relevant integration from the Integration drop-down menu. If not, select Other.
5. Use the checkboxes to define the desired access levels. If you have selected an integration, the recommended access levels will be preselected.
   
   ▶︎ Employees: Select Read to allow third-party systems to pull employee data from Personio and Write to allow them to create and update data in Personio.
   
   ▶︎ Attendances: Select Read to allow third-party systems to pull attendance data from Personio and Write to allow them to create, update and delete attendances in Personio.
   
   ▶︎ Absences: Select Read to allow third-party systems to pull absence data from Personio and Write to allow them to create and delete absences in Personio.
   
   ▶︎ Documents: Select Read to allow third-party systems to pull document category IDs from Personio. This is needed if you want to use the Write permission to allow them to send documents to a Personio employee profile.
   
   ▶︎ Custom Reports: Select Read to allow third-party systems to retrieve all existing custom reports from Personio. Learn more about the Personio Custom Reports API.
   
   

   Note
   If you select the Custom Reports checkbox, all attributes added to a custom report will be retrievable, no matter if the attribute has been whitelisted under Readable employee attributes or not.

6. If you select Read next to Employees, the Readable employee attributes drop-down menu will appear. Choose the employee attributes that should be transferred from Personio. If you have selected an integration, the recommended attributes will be preselected.
   
   

   Tip
   For more information on the access levels that need to be assigned for a specific integration, read the dedicated article in our Integrations section.

7. To generate the API credentials (client ID and secret), click Generate new credential. A message will display confirming that the credentials have been created.
   
   

   Note
   You will need the client ID and secret to activate the relevant integration. For more information, read our article Activate integrations from the Marketplace. Your credentials can be used to access account data and should be treated the same as a password. Keep your credentials confidential. Never share them with third parties.

Manage API credentials 

Update API credentials

Follow the steps below if you want to update the name of the API credentials, the access levels or the readable employee attributes. The client ID and secret cannot be updated.

1. Go to Settings > Integrations > API credentials.
2. Click on the relevant credentials.
3. In the sidebar that appears, make the required updates.
4. Click on Save to implement the updates.

Disable API credentials 

If you temporarily want to disable API credentials, follow these steps:

1. Go to Settings > Integrations > API credentials.
2. In the list of all existing API credentials, toggle the switch beside the relevant credentials to Off.
3. The credentials will be disabled and the exchange of data will cease until the API credentials are re-enabled.

Re-enable API credentials

If you want to re-enable API credentials that have been temporarily disabled from working, follow these steps:

1. 1. Go to Settings > Integrations > API credentials.
   2. In the list of all existing API credentials, toggle the switch beside the relevant credentials to On.
   3. The credentials will be re-enabled and the exchange of data will resume.

Remove API credentials

If you want to permanently delete and stop API credentials from working, follow these steps:

1. 1. Go to Settings > Integrations > API credentials.
   2. Click on the relevant credentials.
   3. In the sidebar that appears, click the bin icon and confirm that you want to remove the API credentials.
   4. The credentials will be permanently removed. 

Technical documentation

All the documentation for our APIs, including endpoints, information about the precise data transferred and technical tutorials, is available in our Developer Hub.