Häufig gestellte Fragen über Integrationen und APIs – Personio

Dieser Artikel behandelt häufig gestellte Fragen über Integrationen und APIs in Personio.

Warum ist der Button Individuelle Integration erstellen in meinem Account nicht sichtbar?

Zum Erstellen individueller API Zugriffsdaten ist der Core Pro Plan erforderlich. Dabei handelt es sich um eine Einschränkung des Plans, kein Problem mit Zugriffsrechten. Mit einer Admin-Rolle erhalten Sie die richtigen Zugriffsrechte, aber keine Core Pro Funktionen. Wenn die Schaltfläche Individuelle Integration erstellen in Marketplace > Verbundene Integrationen nicht sichtbar ist, überprüfen Sie Ihren Plan unter Einstellungen > Account & Support > Abonnement & Abrechnung. Wenn Sie auf Core sind, müssen Sie ein Upgrade auf Core Pro durchführen, um auf diese Funktion zuzugreifen.

Kann ich mit der Personio API historische Gehaltsdaten abrufen?

Die Endpunkte der Personio API geben nur aktuelle Attributwerte zurück. Um historische Gehaltsdaten abzurufen, müssen Sie einen Bericht erstellen und über die API abrufen.

Navigieren Sie zu Analysen.
Klicken Sie auf Bericht erstellen und wählen Sie Leerer Bericht mit Änderungen an Mitarbeitenden.
Fügen Sie die Gehaltsattribute hinzu, die Sie verfolgen möchten. Der Bericht enthält alte und neue Werte sowie das Wirksamkeitsdatum jeder Änderung.
Speichern Sie den Bericht.
Wählen Sie ihn in der Berichtsliste aus, klicken Sie auf API-Zugriff verwalten und wählen Sie Aktiviert.
Navigieren Sie zu Marketplace > Verbundene Integrationen.
Wählen Sie die entsprechende individuelle Integration und aktivieren Sie den Lesezugriff für Berichte.
Klicken Sie auf Aktualisieren.
Rufen Sie die Daten mit der API für Berichte v2 ab. Endpunkt: https://api.personio.de/v2/reports/attributes.

Erfahren Sie mehr über die API für Berichte v2 und die API-Referenz zum Developer Hub.

Warum zeigt eine verbundene Integration immer noch einen alten Wert an, nachdem ich eine Attributoption umbenannt habe?

Das Umbenennen einer Option in einem Auswahllistenattribut aktualisiert nur das Anzeigelabel in Personio. Der Datenbankwert, den Personio an verbundene Integrationen sendet, bleibt gleich, und Sie können ihn nicht ändern. Um den Wert zu aktualisieren, den Ihre Integration erhält, erstellen Sie eine neue Option mit dem richtigen Namen. Der Name, den Sie zuerst eingeben, wird zum neuen Datenbankwert. Erfahren Sie mehr über das Beheben von Datenbankwerten und Anzeigelabels.

Kann ich Arbeitszeitmodelle von Mitarbeitenden über die Personio API abrufen?

Ja. Arbeitszeitmodelle sind Teil der über die Mitarbeitenden-API v1 verfügbaren Mitarbeitendendaten. Um darauf zugreifen zu können, aktivieren Sie den Lesezugriff für Mitarbeitende in Ihrer Integration unter Marketplace > Vernetzte Integrationen.

Sie können Arbeitszeitmodelle mit diesen Endpunkten abrufen:

Die API gibt das aktuelle Arbeitszeitmodell jedes Mitarbeiters zurück. Sie gibt keine historischen Daten zu Arbeitszeitmodellen zurück. Arbeitszeitmodelldaten mit täglicher Granularität sind in v2 nicht verfügbar. Verwenden Sie für diese Daten den v1-Endpunkt.

Wie rufe ich mit der Personio API Abwesenheitsdaten für alle Mitarbeitenden ab?

Verwenden Sie den Endpunkt GET /v2/absence-periods, um Abwesenheitszeiträume, einschließlich aller Abwesenheitsarten und deren Daten, für Ihre Mitarbeitenden abzurufen.

So können Sie das einrichten:

Gehen Sie zu Marketplace > Verbundene Integrationen.
Wählen Sie Ihre individuelle Integration aus, und aktivieren Sie Lesezugriff für Abwesenheit.
Rufen Sie den Endpunkt GET /v2/absence-periods auf. Sie können nach Mitarbeitenden, Abwesenheitsart oder Datumsbereich filtern.

Besuchen Sie den Developer Hub für die vollständige Endpunktdokumentation und verfügbare Filter.

Kann ich mit der Personio API Vertretungsdaten für Abwesenheiten abrufen?

Nein. Vertretungsdaten sind mit der Personio API nicht verfügbar. Sie können eine Vertretung angeben, wenn Sie eine Abwesenheit über die API erstellen, aber der Endpunkt GET /v2/absence-periods gibt das Feld Vertretung nicht zurück. Es steht kein Endpunkt zum Abrufen von Vertretungsdaten zur Verfügung.

Warum werden Abteilung, Team und Position nicht in meiner API-Antwort angezeigt?

Abteilung, Team und Position sind beschäftigungsbezogene Attribute. Der Standard-Endpunkt für Mitarbeitendendaten gibt diese Informationen nicht zurück, selbst wenn Sie in Ihren API-Zugriffsdaten Lesezugriff für Mitarbeitende aktiviert haben. Um sie abzurufen, verwenden Sie stattdessen diese Endpunkte:

Abteilung, Team und Position: GET /v2/persons/{person-id}/employments
Übergeordnete Abteilungen: GET /v2/org-units

Der Organisationseinheiten-Endpunkt gibt nur Abteilungen der obersten Ebene (übergeordnet) zurück. Dieser Endpunkt gibt keine Unterabteilungen innerhalb einer Abteilungshierarchie zurück.

Für Attribute wie Geburtsdatum, die in der Standardantwort zu Mitarbeitenden angezeigt werden, müssen Sie keine Änderungen vornehmen.

Wie rufe ich Stellenkatalogdaten (Stellenbezeichnung, Stellenfamilie und Stellenebene) mit der Personio API ab?

Stellenkatalogattribute sind mit der Personio API verfügbar. Verwenden Sie diese Endpunkte:

Alle Stellen auflisten: GET /v2/jobs
Eine einzelne Stelle abrufen: GET /v2/jobs/{id}

Um den Zugriff einzurichten, öffnen Sie Ihre individuelle Integration, und aktivieren Sie den Zugriff für den Stellenkatalog. Um Daten über Gehaltsbänder einzubeziehen, sollte auch der Zugriff für Gehaltsbänder aktiviert werden.

Mehr über die Endpunktdokumentation erfahren Sie im Developer Hub.

Kann ich die Unterattribute des Attributs Kind über die Personio API abrufen?

Nein. Unterattribute des Attributs Kind, wie erwartetes Fälligkeitsdatum und Geburtsdatum des Kindes, sind mit der Personio API (v1 oder v2) nicht verfügbar. Dies gilt sowohl für den direkten API-Zugriff als auch für Berichte, die mit der API exportiert werden.

Kann ich Datenimporte in Personio durchführen, ohne die API zu verwenden?

Ja. Sie können Daten importieren, indem Sie die in Personio integrierten Vorlagen importieren – dafür sind keine API und kein Entwicklungsaufwand erforderlich. Unterstützt werden Daten zu Mitarbeitenden, Anwesenheiten, Abwesenheit und Gehalt.

Ist für Marketplace-Integrationen der Core Pro Plan erforderlich?

Nein. Marketplace-Partnerintegrationen sind in allen Core Plänen verfügbar. Sie benötigen Core Pro nur, wenn Sie Ihre individuelle Integration über die Personio Public API erstellen möchten.

Warum wird meine Integration in verbundenen Integrationen ohne Logo angezeigt?

Wenn eine Marketplace-Integration unter Marketplace > Verbundene Integrationen ohne Logo angezeigt wird, bedeutet dies, dass Sie die Integration einrichten, indem Sie API-Zugriffsdaten manuell erstellen, anstatt im Marketplace auf Verbinden zu klicken. Dadurch wird ein individueller Eintrag für Zugriffsdaten anstelle eines Eintrags für Marketplace-Integrationen erstellt. Deshalb wird die Integration ohne Logo angezeigt. Personio empfängt mit Ihren individuellen Zugriffsdaten weiterhin Daten aus dem Partnertool, die Integration wird jedoch nicht offiziell mit dem Marketplace-Eintrag verknüpft.

Dies bedeutet, dass der Partner möglicherweise nicht automatisch Aktualisierungen von Zugriffsdaten oder Authentifizierungen für Sie verwaltet. Um die offizielle Marketplace-Version zu verwenden, in der der Partner die Integration verwaltet, heben Sie die Verbindung mit dem individuellen Eintrag auf und verbinden Sie ihn erneut über den Marketplace, indem Sie auf der Seite der Integration auf Verbinden klicken. Wenn die Integration funktioniert und Sie sie nicht neu konfigurieren möchten, wenden Sie sich direkt an das Support-Team des Partners, um zu bestätigen, dass er die erforderlichen Updates auf seiner Seite vornimmt.

Warum synchronisiert meine Marketplace-Integration nicht alle Datentypen?

Der Partner entscheidet, welche Datentypen seine Integration synchronisiert, nicht Personio. Die Daten sind in Personio verfügbar, aber die Integration des Partners steuert, was er abfragt und sendet. Wenn eine Integration einen Datentyp, den Sie erwarten, nicht synchronisiert, ist das normalerweise eine Implementierungsentscheidung des Partners. Es ist kein Fehler, der sich beheben lässt. Um weitere Datentypen anzufragen oder sich über teilweise Synchronisierung zu erkundigen, wenden Sie sich bitte direkt an den Partner.

Kann ich eine bidirektionale Synchronisierung aktivieren, damit Daten von einer Drittanbieter-Integration an Personio zurückgegeben werden?

Die öffentliche API von Personio kann Daten zu Mitarbeitenden, Abwesenheit, Anwesenheiten und Recruiting aus externen Systemen empfangen. Marketplace-Partnerintegrationen synchronisieren Daten jedoch oft nur in eine Richtung – in der Regel von Personio zum Partner. Das hängt von der Art und Weise ab, wie der Partner die Integration erstellt hat, nicht von Ihren Berechtigungen.

Personio besitzt oder kontrolliert den Integrationscode des Partners nicht. Dies bedeutet, dass wir keine bidirektionale Synchronisierung mit einer Integration hinzufügen können, die der Partner nicht unterstützt.

Wenn die Integration im Marketplace aufgelistet wird, überprüfen Sie sie auf detaillierte Angaben dazu, welche Daten sie synchronisiert. Gehen Sie nicht davon aus, dass alle Funktionen einer Integration auf dem Marketplace aufgeführt sind – Einträge beschreiben möglicherweise nicht das vollständige Synchronisierungsverhalten. Fragen Sie direkt beim Partner nach, was die Integration tatsächlich unterstützt. Daten können auch an Personio zurückgegeben werden. Dazu muss der Partner oder Ihr IT-Team die Funktion mithilfe der Personio API erstellten. Wenn Sie unsicher sind, was eine bestimmte Integration unterstützt, wenden Sie sich direkt an den Partner.

Warum finde ich beim Verbinden einer Integration das Attribut „Arbeitsort“ nicht?

Einige Drittanbieter-Integrationen bezeichnen das Attribut Standort von Personio als „Arbeitsort“. Gemeint ist dasselbe – der physische Standort des Mitarbeiters. Wenn eine Integration ein Attribut „Arbeitsort“ erfordert und Sie es nicht finden können, überprüfen Sie, ob Sie Standorte in Personio eingerichtet haben:

Gehen Sie zu Einstellungen.
Klicken Sie im Abschnitt Unternehmen auf Standorte.
Fügen Sie einen Standort hinzu, wenn keiner vorhanden ist, oder überprüfen Sie, ob Sie vorhandene Standorte eingerichtet haben.
Sobald Sie einen Standort eingerichtet haben, wird das Attribut Standort in den Mitarbeitendenprofilen verfügbar. Die Integration kann dann die entsprechende Zuordnung vornehmen.

Warum werden meine Abwesenheitsdaten nicht synchronisiert, obwohl eine Drittanbieter-Integration als verbunden angezeigt wird?

Personio stellt eine REST-API bereit, was bedeutet, dass es Daten nicht proaktiv an verbundene Tools sendet. Eine Drittanbieter-Integration muss die benötigten Daten aktiv anfordern (ziehen). Beispielsweise muss sie Abwesenheitszeiträume abfragen, nachdem jemand sie genehmigt hat. Personio hat keinen Einblick, ob ein Drittanbieter-Tool diese Anfrage gestellt oder warum sie das unterlassen hat.

Stellen Sie sicher, dass die für die Integration eingerichteten API-Zugriffsdaten Lesezugriff für die relevanten Daten enthalten (z. B. Abwesenheit).
Wenden Sie sich an das Support-Team der Integration und bitten Sie es, ihre Protokolle auf die betroffenen Datensätze zu überprüfen.
Das Team kann prüfen, ob ihr System die Daten von Personio angefordert hat und welche Daten Personio zurückgegeben hat.

Gibt es eine Sandbox- oder Testumgebung zum Entwickeln einer Personio API-Integration?

Personio bietet keine kostenlose Sandbox-Umgebung für die API-Entwicklung an. Im Rahmen unseres Premium Support-Plans steht eine spezielle Sandbox-Umgebung zur Verfügung.

Um API-Aufrufe zu testen, ohne echte Mitarbeitendendaten zu verwenden, erstellen Sie in Ihrem aktiven Account eine Reihe von Dummy-Mitarbeitendenprofilen mit fiktiven Namen und Daten. Verwenden Sie diese Profile, um Ihre API-Aufrufe zu testen und die Antworten zu beurteilen. Löschen oder anonymisieren Sie die Dummy-Profile, wenn Sie fertig sind.

Wie synchronisiere ich Projekte aus einem externen Tool in Personio mit der API zur projektbasierten Zeiterfassung?

Sie können Projekte in zwei Schritten synchronisieren:

In Personio erstellen Sie zuerst die Projekte. Verwenden Sie den Projekt-API-Endpunkt, um die einzelnen Projekte zu erstellen. Fügen Sie eine Projekt-ID hinzu, die mit der Kennung in Ihrem externen Tool übereinstimmt.
Übermitteln Sie Zeiteinträge, die mit diesen Projekten verknüpft sind. Sobald die Projekte in Personio existieren, verwenden Sie den Anwesenheits-API-Endpunkt, um Anwesenheitsdatensätze zu übermitteln. Fügen Sie in jedem Eintrag die Projekt-ID hinzu. Das verknüpft die erfasste Zeit zur projektbezogenen Zeiterfassung mit dem richtigen Projekt.

Um auf den Projektendpunkt zuzugreifen, aktivieren Sie in Ihren API-Zugriffsdaten den Zugriff auf Anwesenheiten (Lesezugriff, Schreibzugriff oder beides). Es gibt keine separate Berechtigung für Projekte. Erfahren Sie mehr über die Endpunktdokumentation.

Kann ich automatische Berichte für Ereignisse im Mitarbeitendenlebenszyklus wie Neuanstellungen, Austritte und Anwesenheitsänderungen einrichten?

Sie können das automatische Senden von Berichten nicht direkt in Personio planen. Es gibt keine integrierte Funktion, die Berichte in einer festgelegten Häufigkeit sendet oder den Export eines Berichts für ein Lebenszyklusereignis auslöst. Um diese Daten zu verfolgen, gehen Sie zu Analysen > Metriken oder Analysen > Berichte, und führen Sie Berichte manuell aus. Dort finden Sie viele vordefinierte Berichtsvorlagen. Wenn Sie programmatischen Zugriff auf Berichtsdaten benötigen, können Sie Berichte mit der API für Berichte v2 abrufen. Sie können dann Ihren eigenen Ablauf extern erstellen.

Kann ich ein KI-Tool wie Claude oder ChatGPT mit Personio verbinden?

Überprüfen Sie, ob das Tool, das Sie verbinden möchten, im Marketplace aufgeführt ist. Ist dies nicht der Fall, können Sie es trotzdem über die öffentliche API und Webhooks mit Personio verbinden. So können Sie Daten wie Mitarbeitendenprofile, Abwesenheiten, Anwesenheiten und Recruiting-Informationen austauschen. Für das Einrichten der Verbindung ist Ihre IT-Abteilung oder ein externes IT-Dienstleistungsunternehmen zuständig. Der Personio-Support kann Fragen zur API beantworten, Ihnen aber nicht dabei helfen, individuellen Code zu schreiben oder zu überprüfen.

Kann ich verhindern, dass Slack oder Microsoft Teams den Geburtstag oder Jahrestag der Betriebszugehörigkeit von Mitarbeitenden bekannt gibt?

Nein. Kanalaktualisierungen gelten für alle in der Abteilung, im Team oder am Standort, die diesem Kanal zugeordnet sind – Sie können keine einzelnen Mitarbeitenden ausschließen. Sie haben zwei Möglichkeiten: Deaktivieren Sie diesen Ereignistyp für den gesamten Kanal, oder grenzen Sie die Abteilung, das Team oder den Standort, dem Sie die Aktualisierung zuweisen, enger ein, sodass der Mitarbeiter nicht einbezogen wird.

Kanalaktualisierungen sind davon abhängig, ob der Status einer Mitarbeiterin oder eines Mitarbeiters in Personio aktiv oder inaktiv ist, nicht vom Status der Auszeit. Mitarbeitende in Auszeit oder einer anderen Abwesenheitsart zählen weiterhin als aktiv und erscheint weiterhin in Aktualisierungen. Sie können Aktualisierungen nicht nach Abwesenheitsart filtern. Eine bestimmte Person kann nur ausgeschlossen werden, wenn sie in Personio als inaktiv markiert wird.

Kann ich bestimmte Abwesenheitsarten, wie Mutterschutz oder Elternzeit, von der täglichen Abwesenheitsaktualisierung auf Slack ausnehmen?

Nein. Wenn eine Aktualisierung Abwesenheiten enthält, beinhaltet sie alle Abwesenheitsarten. Sie können nicht nach Typ filtern. Sie können eingrenzen, für wen die Aktualisierung gilt, indem Sie sie einer bestimmten Abteilung, einem Team oder einem Standort zuweisen. Das ändert jedoch die Zielgruppe und nicht, welche Abwesenheitsarten angezeigt werden.

Kann ich mehr als einen Slack-Workspace mit meinem Personio Account verbinden?

Nein, Sie können nur einen Slack-Workspace pro Personio Account verbinden. Wenn Sie eine zweite Gesellschaft mit einem separaten Slack-Workspace haben, können Sie die Personio API als Abhilfe verwenden, um Abwesenheitsbenachrichtigungen an diesen Workspace zu senden. Gehen Sie hierzu wie folgt vor:

Verwenden Sie den Endpunkt Mitarbeitende auflisten, um Mitarbeitende abzurufen und nach Gesellschaft zu filtern.
Verwenden Sie den Endpunkt Abwesenheitszeiträume auflisten, um Abwesenheiten für diese Mitarbeitenden abzurufen.
Verwenden Sie die Slack API, um die Ergebnisse in einen Kanal im zusätzlichen Workspace zu veröffentlichen.

Erfahren Sie mehr über die Zugriffseinrichtung für die API.
Dokumentation zu Endpunkten finden Sie im Developer Hub.

Kann ich Slack so konfigurieren, dass halbtägige oder stündliche Abwesenheiten genau angezeigt werden?

Nein. Die automatische Funktion für den Slack-Status unterstützt nur ganztägige Abwesenheiten. Halbtägige und stündliche Abwesenheiten werden in Slack als ganztägige Abwesenheiten angezeigt. Es gibt keine Einstellung, um das zu ändern. Die Abwesenheitsdaten in Personio bleiben genau. Diese Einschränkung betrifft nur die Anzeige des Slack-Status.

Wenn halbtägige Abwesenheiten in Slack dargestellt werden sollen, können Sie eine individuelle Lösung entwickeln. Sie verwenden hierzu Personio-Webhooks und API-Endpunkte um Slack-Statusaktualisierungen basierend auf bestimmten Abwesenheitsdaten auszulösen. Für das Einrichten der Verbindung ist Ihre IT-Abteilung oder ein externes IT-Dienstleistungsunternehmen zuständig. Der Personio-Support kann Fragen zur API beantworten, Ihnen aber nicht dabei helfen, individuellen Code zu schreiben oder zu überprüfen.

Warum bleibt meine Integration im Status Ausstehend hängen?

Der Status Ausstehend bedeutet, dass Personio bereit ist und darauf wartet, dass die Integration die erste API-Anfrage stellt. Der Status ändert sich in Verbunden, sobald die Integration Daten sendet. Wenn der Status Ihrer Integration über einen längeren Zeitraum Ausstehend lautet, liegt ein Problem beim Partner vor. Personio hat keinen Einblick, wie Drittunternehmen Integrationen entwickeln oder warum sie keine Daten senden. Rufen Sie Marketplace > Verbundene Integrationen auf, um den Status zu überprüfen, und wenden Sie sich dann an das Support-Team des Partners und nicht an Personio, um Untersuchungen anzustellen.

Kann ich mehrere Integrationen gleichzeitig ausführen?

Ja. Die Personio API reagiert auf Anfragen von verbundenen Tools, anstatt sie zu initiieren. Das bedeutet, dass das gleichzeitige Ausführen mehrerer Integrationen standardmäßig keinen Konflikt verursacht. Ausnahme ist, wenn zwei Integrationen gleichzeitig Schreibzugriff auf denselben Datentyp haben, beispielsweise auf Anwesenheiten. Wenn beide dieselben Datensätze hinzufügen oder aktualisieren, kann dies zu widersprüchlichen Daten oder Überschreibungen führen. Wenn Sie mehrere Integrationen für dieselben Daten ausführen, überprüfen Sie, ob mehrere Schreibzugriff darauf haben. Stimmen Sie sich bei Bedarf mit allen Partnern ab.

Kann ich einen zweiten Account mit einer bereits genutzten Marketplace-Integration verbinden?

Sie können die vorhandenen Zugriffsdaten verwenden, um einen zweiten Account mit derselben Integration zu verbinden. Sie können jedoch keinen zweiten Satz an API-Zugriffsdaten für dieselbe Marketplace-Integration erstellen. Bei Verwendung einer Marketplace-Integration oder Verbindung einer Integration über die öffentliche API fallen bei Personio keine zusätzlichen Kosten an, sofern für Ihren Account der Core Pro-Plan gilt, der die API-Nutzung beinhaltet. Einige Partnertools haben möglicherweise eigene Preise. Fragen Sie direkt beim Partner nach, wenn Sie unsicher sind.

Kann ich bestimmte Mitarbeitende von einer Marketplace-Integration ausschließen?

Bei den meisten Marketplace-Integrationen gibt es keine Option, einzelne Mitarbeitende oder eine bestimmte Gruppe auszuschließen. Alle Mitarbeitenden werden standardmäßig synchronisiert. Einige Payroll-Integrationen wie Xero, ADDISON und Loket bilden eine Ausnahme. Sie enthalten ein Attribut, mit dem Sie einzelne Mitarbeitende von dieser spezifischen Lohnbuchhaltung ausschließen können. Wenn es sich nicht um eine Payroll-Integration handelt, ist diese Funktion nicht verfügbar.

Einige Integrationen bieten die Filterung innerhalb ihrer eigenen Einstellungen. Dies ändert jedoch in der Regel nur, wie das Partner-Tool Mitarbeitende anzeigt – die Datenübertragung in dieses Tool erfolgt trotzdem. Filteroptionen für die einzelnen Integrationen finden Sie in der Dokumentation des Partners.

Finden Sie die Antworten, die Sie brauchen