This article addresses the most frequently asked questions about integrations and APIs in Personio.

Plans and Access

Why is the Create custom integration button not visible in my account?

Creating custom API credentials requires the Core Pro plan. This is a plan restriction, not an access rights issue. Having an Administrator role gives you the correct access rights, but it doesn't include Core Pro features. If the Create custom integration button isn't visible in Marketplace > Connected Integrations, check your plan in Settings > Account & support > Subscription & billing. If you're on Core, you need to upgrade to Core Pro to access this feature.

Do Marketplace integrations require the Core Pro plan?

No. Marketplace partner integrations are available on all Core plans. You need Core Pro only if you want to build your own custom integration using the Personio public API.

Can I connect an AI tool like Claude or ChatGPT to Personio?

Check if the tool you want to connect is listed in the Marketplace. If it's not, you can still connect it to Personio using the public API and webhooks. This allows you to exchange data including employee profiles, time off, attendance records, and recruiting data. Your IT department or an external IT service provider is responsible for building the connection. Personio Support can answer questions about the API but can't help write or review custom code.

Is there a sandbox or test environment for developing a Personio API integration?

Personio doesn't offer a free sandbox environment for API development. A dedicated sandbox environment is available as part of our Premium Support plan.

To test API calls without using real employee data, create a set of dummy employee profiles with fictitious names and data in your live account. Use these profiles to test your API calls and review the responses. Delete or anonymize the dummy profiles when you're done.

What do the API configurations and Marketplace integration employee role permissions do?

These are two separate employee role permissions:

Marketplace integration: set up and manage third-party integrations in the Personio Marketplace.
API configurations: view and manage API credentials used for third-party Marketplace or custom integrations.

Neither role permission controls what data the API can retrieve. That depends on the integration's own access rights, not the employee's role.

An integration has stopped working — can I use the Audit Log to see what changed?

No. The Audit Log doesn't record changes made to integrations. and it doesn't track API activity. API calls made with third-party Marketplace or custom integration credentials, such as data reads or writes, don't appear in the Audit Log. Learn how to troubleshoot integrations and APIs.

How do I manage or update the scopes of my API credentials?

Go to Marketplace > Connected integrations to see all your current integrations, whether they belong to Marketplace integrations or custom integrations you created yourself.

For Personio-built integrations, scopes are fixed and cannot be changed.
For third-party Marketplace integrations, Personio sets up the correct scopes when you connect the integration. While you can view and adjust these in Marketplace > Connected integrations > Access rights you shouldn't need to change them. If something has stopped working, reconnect the integration rather than adjusting scopes manually as this restores the correct defaults.

To create a new integration with the additional read rights you need, for example, for employee attributes, attendance, or time off, you need to create a custom integration. This requires the Core Pro plan. On the Core plan, you can connect Marketplace integrations but cannot create or edit a custom integration's scopes.

What can my IT team access if I give them API access?

It depends on how you set up their access. There are two scenarios:

You created a custom integration and shared the Client ID and secret with them. Anyone with these credentials can only access the data you enabled for those credentials. For example, if you didn't grant read access to salary-related attributes, they cannot retrieve them.
You gave them the Marketplace integration or API configurations role permissions. These permissions allow someone to create or manage API credentials themselves, with the ability to grant themselves access to almost any data in Personio, including salaries and other confidential HR information. Learn more about integrations role permissions.

If their credentials have read access to Reports or Custom Reports, and those reports contain sensitive data, they can also access it through the API. For new report builder reports, you need to enable each report for API access. Only reports you enable are retrievable with the API. Enabling Custom Reports access grants access to all custom reports, and you cannot restrict this per report.

To control what anyone with API access can retrieve, review who has edit rights for Marketplace Integration and API configurations, and check the scopes on any existing API credentials.

API data availability and retrieval limits

Can API credentials be used to access data that an employee cannot see in the Personio interface?

Yes. API credentials act like admin-level access. Anyone with access to API credentials can retrieve almost all data from the Personio account through the API, regardless of their permissions in Personio. Employee role permissions apply to the interface only — they don't restrict what can be retrieved through the API. For this reason, you should only grant API credential access to trusted users.

Can I limit API access to only specific data types?

Yes. When you create a custom integration, you choose which data types it can access. If you enable only read access for a particular data type, the integration can only retrieve data related to that. For example, Read access for Time off means the integration can only retrieve absence data — it cannot access Employees, Documents, Salaries, or any other data type.

Can I retrieve historical salary data using the Personio API?

The Personio API endpoints return current attribute values only. To retrieve historical salary data, you need to create a report and retrieve it via the API.

Go to Analytics
Click Create report and select Employee change blank report.
Add the salary attributes you want to track. The report shows old and new values along with the effective date of each change.
Save the report.
In the reports list, select it, click Manage API access, and select Enabled.
Go to Marketplace > Connected Integrations.
Select the relevant custom integration and enable Read access for Reports
Click Update.
Retrieve the data using the Report API v2. Endpoint: https://api.personio.de/v2/reports/attributes.

Learn more about how to use the Report API v2 and the Developer Hub API reference.

Can I restrict an API credential's access to specific compensation types?

No. API credential permissions are granted at the resource level. If you grant a custom integration access to the Compensations permission, it can access all compensation types for all employees — you cannot limit this to a specific type, such as one-time or recurring compensation.

The only available scope restriction is by legal entity. You can select which legal entities the integration retrieves compensation data for, which limits access to employees in those entities.

If you want to prevent the integration from accessing other data types such as employee data or attendance, set up a dedicated integration with only the Compensations permission enabled.

Can I retrieve employee work schedules using the Personio API?

Yes. Work schedules are part of the employee data available through the v1 Employee API. To access them, enable Read access for Employees on your integration in Marketplace > Connected Integrations.

You can retrieve work schedules using these endpoints:

The API returns each employee's current work schedule. It doesn't return historical schedule data. Work schedule data with daily granularity isn't available in v2. Use the v1 endpoint for this data.

Why don't department, team, and position appear in my API response?

Department, team, and position are employment-related attributes. The standard employee data endpoint doesn't return them, even if you have Read access for Employees enabled in your API credentials. To retrieve them, use these endpoints instead:

Department, team, and position: GET /v2/persons/{person-id}/employments
Top-level departments: GET /v2/org-units

The org-units endpoint returns top-level (parent) departments only. This endpoint doesn't return sub-departments within a department hierarchy.

You don't need to change anything for attributes like date of birth that do appear in the standard employee response.

How do I retrieve job catalog data (job name, job family, and job level) using the Personio API?

Job catalog attributes are available with the Personio API. Use these endpoints:

List all jobs: GET /v2/jobs
Retrieve a single job: GET /v2/jobs/{id}

To set up access, open your custom integration and enable access for Job catalog. To include salary band data, also enable Salary Bands access.

Learn about endpoint documentation in the Developer Hub.

Can I retrieve the sub-attributes of the child attribute using the Personio API?

No. Sub-attributes of the child attribute, such as expected due date and child's date of birth, are not available with the Personio API (v1 or v2). This applies to both direct API access and reports exported with the API.

How do I retrieve time off data for all employees using the Personio API?

Use the GET /v2/absence-periods endpoint to retrieve time off periods, including all time off types and their dates, for your employees.

To set this up:

Go to Marketplace > Connected integrations.
Select your custom integration and enable Read access for Time off.
Call the GET /v2/absence-periods endpoint. You can filter by employee, absence type, or date range.

Visit the Developer Hub for full endpoint documentation and available filters.

Can I retrieve substitute data for time offs using the Personio API?

No. Substitute data isn't available with the Personio API. You can include a substitute when creating a time off using the API, but the GET /v2/absence-periods endpoint doesn't return the substitute field. There is no endpoint available to retrieve substitute data.

How do I sync projects from an external tool into Personio with the API for project-based time tracking?

You can sync projects using a two-step process:

In Personio, create the projects first. Use the Projects API endpoint to create each project. Include a project ID that matches the identifier in your external tool.
Submit time entries linked to those projects. Once the projects exist in Personio, use the Attendance API endpoint to submit attendance records. Include the project ID in each entry. This is what links the tracked time to the correct project for project-based time tracking.

To access the Projects endpoint, enable Attendances access (read, write, or both) in your API credentials. There's no separate Projects permission. Learn more about the endpoint documentation.

Why can't I find a Projects option in my custom integration's API credential settings?

To access the Projects API endpoint in a custom integration, you need to enable Attendances access (Read and/or Write) in your API credentials. There is no separate Projects permission — the Projects API endpoint is covered by Attendances access.

Data import and reporting

Can I import data into Personio without using the API?

Yes. You can import data using Personio's built-in import templates — no API or development work required. Supported types include employees, attendance, time off, and salary.

Can I set up automated reporting for employee lifecycle events like new hires, departures, and attendance changes?

You cannot schedule automated report delivery directly in Personio. There's no built-in feature that sends reports at a set frequency or triggers a report export on a lifecycle event. To track this data, go to Analytics > Metrics or Analytics > Reports and run reports manually. You can find many predefined report templates there. If you need programmatic access to report data, you can retrieve reports using the Report API v2. You can then build your own scheduled pipeline externally.

Marketplace integrations

Why is a connected integration still showing an old value after I renamed an attribute option?

Renaming an option in a list of options attribute only updates the display label in Personio. The database value — which is what Personio sends to connected integrations — stays the same and you cannot change it. To update the value your integration receives, create a new option with the correct name. The name you enter first becomes the new database value. Learn more about how to fix database values and display labels.

Why is my Marketplace integration stuck on Pending status?

A Pending status means Personio is ready and waiting for the integration to make its first API request. The status changes to Connected automatically once the integration sends data — you cannot update it manually.

If your integration is showing Pending, check the configuration in the external system first to make sure it's actively sending requests to Personio. You can review what data the integration can access in Personio by going to Marketplace > Connected integrations, clicking the integration, and selecting the Access Rights tab. The external system, not Personio, controls how the integration behaves.

If your integration has shown Pending for an extended period, the issue is on the partner's side. Personio has no visibility into how third-party partners build integrations or why they aren't sending data. If the partner tool shows the integration as active on their side, troubleshoot the issue before contacting the partner — the cause may be a credential type mismatch you can fix yourself. Contact the partner's support team, not Personio, to investigate.

Why does my Marketplace integration report missing API permissions, and how do I fix it?

To fix missing API permissions on a Marketplace integration, disconnect and reconnect it:

Go to Marketplace > Connected integrations.
Select the integration.
Click Disconnect.
Go to Marketplace and search for the integration.
Click Connect.
Click Generate new credential to automatically generate new API credentials with the permissions the integration needs.

If the integration still doesn't work as expected after reconnecting, contact the integration partner's support team for help.

Can I run multiple integrations at the same time?

Yes. Personio's API responds to requests from connected tools rather than initiating them. This means running several integrations at once doesn't cause a conflict by default. The exception is when two integrations both have write access to the same data type, for example, attendance data. If both are adding or updating the same records, this can cause conflicting or overwritten data. If you're running multiple integrations against the same data, check whether more than one has write access to it. Coordinate with each partner if needed.

Can I connect a second account to a Marketplace integration I already use?

You can reuse the existing credentials to connect a second account with that same integration. However, you cannot create a second set of API credentials for the same Marketplace integration. Using a Marketplace integration, or connecting an integration through the public API, doesn't add extra cost on the Personio side, as long as your account has the Core Pro plan, which includes API usage. Some partner tools may have their own separate pricing. Check with the partner directly if you're unsure.

Can I exclude specific employees from a Marketplace integration sync?

For most Marketplace integrations, there's no option to exclude individual employees or a specific group. All employees sync by default. Some payroll integrations, like Xero, ADDISON, and Loket, are an exception. They include an attribute that you can use to exclude individual employees from that specific payroll sync. This isn't available for non-payroll integrations.

Some integrations offer filtering within their own settings. However, this typically only changes how the partner tool displays employees — the data transfer to that tool still happens. For integration-specific filtering options, check the partner's documentation.

What happens after I request an integration that isn't in the Marketplace?

You don't receive an individual confirmation or status update by email once you request an integration. To check progress, visit the Requested integrations page. If Personio decides to build the integration, the status there updates.

Why does my integration show without a logo in Connected integrations?

If a Marketplace integration appears without a logo in Marketplace > Connected integrations, it means you set up the integration by creating API credentials manually rather than by clicking Connect in the Marketplace. This creates a custom credential entry rather than a Marketplace integration entry, which is why it appears without a logo. Personio still receives data from the partner tool using your custom credentials, but Personio doesn't officially link the integration to the Marketplace entry.

This means the partner might not automatically manage credential updates or authentication changes on your behalf. To use the official Marketplace version, where the partner manages the integration, disconnect the custom entry and reconnect using the Marketplace by clicking Connect on the integration's page. If the integration is working and you don't want to reconfigure it, contact the partner's support team directly to confirm they handle any required updates on their side.

Why isn't my Marketplace integration syncing all data types?

The partner decides which data types their integration syncs, not Personio. The data is available in Personio, but the partner's integration controls what it queries and sends. If an integration isn't syncing a data type you expect, this is usually a partner implementation choice. It's not an error to troubleshoot. To request additional data types or ask about partial syncing, contact the partner directly.

How do I re-authenticate an existing Marketplace integration?

If a Marketplace integration loses its connection or you need to refresh its authentication after a credential or API change, you don't need to set it up from scratch.

Go to Marketplace > Connected integrations and select the integration.
Beside Repeat authentication, click Next.
Follow the steps to complete the authorization flow with the partner system.
If prompted, review the field mapping to confirm it's still correct.

If re-authentication doesn't complete successfully, a warning message appears in the integration. Follow the prompt to reconnect.

Can I enable bi-directional sync so data flows back into Personio from a third-party integration?

Personio's public API can receive employee, time off, attendance, and recruiting data from external systems. However, Marketplace partner integrations often only sync data in one direction — usually from Personio to the partner. This depends on how the partner built the integration, not on your permissions.

Personio doesn't own or control the partner's integration code. This means it cannot add two-way sync to an integration that the partner didn't build to support it.

If the integration has a listing in the Marketplace, check it for details on what data it syncs. Don't assume an integration's capabilities based on its Marketplace listing alone — listings may not describe the full sync behavior. Check with the partner directly to confirm what the integration actually supports. Data can flow back into Personio too. To do this, the partner or your IT team needs to build it using the Personio API. If you're unsure what a specific integration supports, contact the partner directly.

Why can't I find the "Office" attribute when connecting an integration?

Some third-party integrations refer to Personio's Workplace attribute as "Office." These are the same concept — the employee's physical work location. If an integration requires an "Office" attribute and you cannot find it, check whether you've set up workplaces in Personio:

Go to Settings.
In the Organization section, click Workplaces.
Add a workplace if none exist, or check that you've set up existing workplaces.
Once you set up a workplace, the Workplace attribute becomes available on employee profiles. The integration can then map to it.

Why isn't my time off data syncing even though a third-party integration shows as connected?

Personio provides a REST API which means it doesn't proactively send data to connected tools. A third-party integration needs to actively request (pull) the data it needs. For example, it needs to query time off periods after someone approves them. Personio has no visibility into whether a third-party tool made that request or why it might not have.

Confirm that the API credentials set up for the integration include read access for the relevant data (for example, time off).
Contact the integration's support team and ask them to check their logs for the affected records.
They can confirm whether their system requested the data from Personio and what data Personio returned.

Users can't log into a third party or custom integration anymore — has something changed with the Personio connection?

Personio has no visibility into changes made to third-party Marketplace or custom integrations. If the issue persists, contact the partner's support team for a third-party Marketplace integration or your IT team for a custom integration.

If users can't log into Personio itself, that's a separate issue. Learn how to troubleshoot SSO login issues.

What's the difference between disabling and disconnecting an integration, and when should I use each?

Disabling a marketplace or custom integration makes the integration inactive but keeps it visible in Marketplace > Connected integrations. Disconnecting a marketplace or custom integration permanently removes the credentials, which you cannot undo. You cannot disable a Personio-built integration.

If you're unsure if an integration is still in use, disable the integration first. If nothing breaks, you can then disconnect it to remove it permanently.

To disable or disconnect a third-party Marketplace integration or custom integration:

Go to Marketplace > Connected integrations.
In the Action column, click the three dots next to the integration.
Click Disable or Disconnect.

What are my options if a tool I want to connect isn't in the Marketplace?

If you're looking to analyse or report on HR data, it's worth checking whether Personio's built-in Analytics area already covers your needs. It includes metrics, KPIs, and custom report building.

If the tool you want — for example, a business intelligence (BI) or analytics tool like Power BI or Tableau — isn't listed in the Personio Marketplace, you have two options depending on what you need

Use an integration platform: integration platforms like Zapier can connect Personio to many other apps without custom development. This works best for workflow automations, for example, triggering an action in another tool when something changes in Personio. Zapier is available as a Marketplace integration.
Build a custom integration using the Personio API: If an integration platform doesn't meet your needs, you can build a custom integration using the Personio API. It requires the Core Pro plan. Your IT team or an external IT provider is responsible for building the connection. Personio Support can answer questions about the API but cannot help write or review custom code.

Why are documents uploaded by a third-party integration landing in the wrong category, and how do I fix it?

When a third-party integration uploads documents to Personio via the API, the category ID in the API request determines the document category. If documents are landing in the wrong category, the integration is using an incorrect category ID.

To find the correct category IDs, call the document categories endpoint: GET /v1/company/document-categories

This returns a list of all available document categories and their IDs. Your API credentials need Read access to Documents for this endpoint to work. Once you have the correct category ID, pass it in the POST /v1/company/documents request when uploading the document to assign it to the right category.

Share the correct category ID with the integration provider so they can update the category mapping on their end.

Custom integrations

How can I find out what an unidentified custom integration in my account is used for?

Personio doesn't store the purpose of a custom integration — it only receives API requests. To investigate an unidentified integration:

Go to Marketplace > Connected integrations, select the integration, and review its API permissions to see what data it can access — for example, Employees, Attendances, or Time off.
Check internally whether anyone in your organization knows what the integration connects to. This might mean asking your IT team, checking any internal documentation about your tech stack, or reaching out to whoever originally set up the integration or managed it previously.
If you still can't identify it, disable it temporarily and monitor whether anything in your systems stops working. If nothing breaks, you can then disconnect it.

Why does my new custom integration show as Pending?

When you create a custom integration in Personio, the status initially shows as Pending. This means Personio is ready to receive requests — you don't need to do anything else in Personio. The status automatically changes to Connected once your integration makes its first successful API call.

If the integration is still showing Pending, the connection hasn't been established yet on your side. Check that your system is correctly using the Client ID and Client Secret generated for the integration. If you need to troubleshoot a failing API call, check the full request (including headers and body), the Client ID used, and the full API response to identify the issue.

Slack and Microsoft Teams

Can I stop Slack or Microsoft Teams from announcing an employee's birthday or work anniversary?

No. Channel updates apply to everyone in the department, team, or workplace mapped to that channel — you cannot exclude a single employee. You have two options: turn off that event type for the whole channel or assign the update to a narrower department, team, or workplace so the employee isn't included.

Channel updates depend on whether an employee's status in Personio is active or inactive, not on their leave status. An employee on leave or any other time off type still counts as active and continues to appear in updates. You cannot filter updates by time off type. The only way to exclude one specific employee is to mark them as inactive in Personio.

Can the Microsoft Teams integration include work-location types like "working from home" or "business trip" in its daily updates?

No. The Teams integration only sends daily channel updates for a fixed set of events: employee time off and return dates, birthdays, work anniversaries, and new employees. It doesn't cover attendance or work-location types such as working from home, remote work, or business trips.

If you want colleagues to see who is working from home or on a business trip, you need a custom integration via API: use the Personio API to retrieve work-location absence data and build a custom integration that posts it to a Teams channel on a schedule. This requires development work by your IT team or an external provider.

Can I exclude specific time off types, like maternity or parental leave, from the daily Slack time off update?

No. If an update includes time off, it includes every time off type. You cannot filter by type. You can narrow who the update applies to by assigning it to a specific department, team, or workplace, but this changes the audience, not which time off types appear.

Can I connect more than one Slack workspace to my Personio account?

No, you can only connect one Slack workspace per Personio account. If you have a second legal entity using a separate Slack workspace, you can use the Personio API as a workaround to send time off notifications to that workspace. To do this:

Use the List Employees endpoint to retrieve employees and filter by legal entity.
Use the List Absence Periods endpoint to retrieve absences for those employees.
Use the Slack API to post the results to a channel in the additional workspace.

Learn more about how to set up API access and find endpoint documentation in the Developer Hub.

Can I get Slack to show half-day or hourly time off accurately?

No. The automated Slack status feature only supports daily time off. Half-day and hourly time off show as full-day time off in Slack. There's no setting to change this. Your time off records in Personio stay accurate. This limitation only affects the Slack status display.

If you need Slack to reflect half-day time off accurately, you can build a custom solution. This solution uses Personio webhooks and API endpoints to trigger Slack status updates based on specific time off data. Your IT department or an external IT service provider is responsible for building the connection. Personio Support can answer questions about the API but can't help write or review custom code.

What are the Partner ID and App ID, and do I need them?

The Partner ID and App ID are headers you can include in Personio API requests to help identify your integration. You set these values yourself. Personio doesn't generate them. If you're building a custom integration, Personio strongly recommends including X-Personio-App-ID, as it helps with debugging and support. Learn more about values and formatting in the Developer Hub.

Recruiting API

How do I fix a 404 error when submitting an application using the Recruiting API?

A 404 response on POST /v1/recruiting/applications usually means the job position is not in Published status. The API only accepts applications for published positions — positions in Draft or any other status return a 404, even if the position exists in Personio.

To fix this, go to Recruiting > Jobs, find the relevant position, and confirm its status. If it's set to Draft, change it to Published, then retry the API request.

Can I upload documents to an existing recruiting application using the API?

No. The API only supports attaching documents when creating a new application, not adding them to one that already exists. If you need to attach documents to an existing application, do this manually in the candidate's profile.

Documents uploaded to the upload endpoint without being immediately referenced in an application creation call are not visible anywhere in Personio. Always complete both steps in the same flow.

Can I download candidate documents like CVs using the Personio API?

You can download candidate application documents using the Document Management API. The Recruiting API itself doesn't include a document download endpoint, but the Document Management API supports this when you use the application_id as the owner_id.

Follow these steps:

Generate a bearer token using your API credentials via the Auth endpoint.
Use the List Applications endpoint to retrieve your application_id values. You can filter by created_at to scope the results.
For each application_id, call the List Document Metadata endpoint using the application_id as the owner_id.
This returns the document_id values for documents attached to that application.
Use each document_id with the Download Document File endpoint to download the file.
You need read access for both Documents and Recruiting in your API credentials.

Can custom attributes and tags written using the Recruiting API be retrieved through the API afterward?

No. The v2 Candidates and Applications endpoints don't return custom attributes or tags in their responses. When you write a custom attribute or tag value using POST, the v2 GET endpoints don't return it. If you need to retrieve or verify this data later, keep a copy in your own system at the time of writing.

Can I update an application's stage or a candidate's status using the Recruiting API?

No. The v2 Recruiting API endpoints (/applications, /candidates, /jobs, and /applications/{id}/stage-transitions) are read-only — they only support GET requests. The only write endpoint in the Recruiting API is POST /v1/recruiting/applications, which creates a new application and cannot update an existing one.

To track stage changes in an external system, poll the read endpoints periodically to detect changes over time. Check the Personio Developer Hub for available webhooks for recruiting events.

Find the answers you need