Wie funktioniert die Personio Recruiting API?

Dieser Artikel beinhaltet Wissenswertes über die von Personio zur Verfügung gestellte Recruiting API Schnittstelle. Die nachfolgende Agenda vermittelt Ihnen einen ersten Überblick über die Inhalte dieses Artikels: 

Bitte beachten Sie, dass Sie für die Anbindung der Recruiting API einen IT Experten hinzuziehen sollten. Eine technische Dokumentation unserer API mit allen Parametern und Detailinformationen finden Sie in unserem Developer Hub

 

Grundlegendes zur API

Personio bietet Ihnen die Möglichkeit über einen XML Feed Inhalte aus Personio abzurufen, um diese auf Ihrer eigenen Karriereseite zu veröffentlichen. Bewerber, die sich über Ihre Karriereseite bewerben, können Sie über die API Schnittstelle in Personio einspielen. Finden Sie hier einen zusammenfassenden Artikel über die Kommunikation zwischen Personio und Ihrer Karriereseite.

Eine API (application programming interface) ist eine sich auf einem Server befindliche Zusammenstellung von Befehlen. Über diese Befehle werden externen, anfragenden Programmen Daten für verschiedene Anfragen zugänglich gemacht. Die Personio Recruiting API ist ein von Personio bereitgestelltes, permanent auf dem Personio Server laufendes Programm.

Wenn zwei Systeme über eine API verbunden sind, sprechen wir von einer Integration. In einer Integration gibt es zwei Seiten: den Server (hier Personio) und den Klienten (Ihre Webseite) der durch einen User (bspw. Ihr Systemadministrator) gesteuert wird. 

 

Kommunikationsprotokoll HTTP 

Anders als Menschen, die verschiedene Satzstellungen und Formulierungen sinngemäß deuten können, brauchen Server und Klient eine eindeutige Ausdrucksweise, um miteinander kommunizieren zu können. Diese nennt sich HTTP (Hyper-Text Transfer Protocol) und ist eine Zusammenstellung von Regeln die besagen, wie z.B. Anfragen und Antworten computerlesbar konfiguriert sein müssen. 

Wenn Sie beispielsweise die URL http://beispiel.de in Ihren Browser eingeben, um eine Webseite aufzurufen bestimmen Sie, dass Ihr Browser die Regeln des HTTP Protokolls anwenden soll. Über dieses und dessen Regeln kommuniziert der Browser nun mit dem Server, der die Webseite bereitstellt. 

 

Anfrage des Klienten

Die Kommunikation in HTTP strukturiert sich über Anfragen des Klienten und Antworten des Servers. Sowohl das Abrufen einer Stelle aus dem XML Feed als auch das Senden einer Bewerbung nach Personio, stellen eine Anfrage dar. 

Um eine funktionierende Anfrage zu senden, übermittelt der Klient vier Anfrage-Bestandteile: 

  • URL (Uniform Resource Locator)
  • Methode
  • Liste der Header
  • Body

Die URL ist eine eindeutige Adresse unter der die API zu erreichen ist.

Die URL um Bewerbungen in Personio einzuspielen lautet: https://api.personio.de/recruiting/applicant. Der letzte Teil der URL ist der Endpunkt. Die Benennung des Endpunkts ist frei wählbar, sollte aber die darüber ausführbaren Aktionen erahnen lassen. 

Die URL um Ihre Stellen aus Personio abzurufen lautet meinaccount-jobs.personio.de/xml.

Die Methode teilt dem Server mit, welche Art von Aktion der Klient vom Server erwartet. Personio erlaubt die Methoden POST und GET. Die Methode POST fügt Bewerbungen in Personio ein, während Sie über GET Stellen aus Personio abrufen können.

Die Liste der Header stellt Meta-Informationen über die Anfrage bereit, wie z.B. den Header User-Agent. Dieser teilt dem Server mit, um welches Gerät es sich bei dem anfragenden Klienten handelt. Basierend auf der Information aus dem Header sendet der Server die Daten in einem für den Klienten passenden Format zurück. 

Der Body Ihrer Anfrage enthält die Parameter, die der Klient zu senden, bzw. abzurufen versucht. Finden Sie genauere Informationen zu den für Personio relevanten Parametern weiter unten im Artikel. 

 

Antwort des Servers

Nachdem der Server eine Anfrage des Klienten erhalten hat, sendet er eine Antwort nach den Regeln des HTTP Protokolls zurück. Die Antwort des Servers beinhaltet einen numerischen Status Code, welcher darüber informiert, ob der Server die Anfrage beantworten konnte und falls nicht, warum nicht. Im Body der Antwort befinden sich bei Erfolg die angefragten, bzw. gesendeten Daten, während der Header Meta-Informationen, wie z.B. eine Information über das Datenformat, liefert.

Gängige Status Codes sind z.B. 

  • 200: Success - alles hat geklappt
  • 400: Bad Request - Irgendwas ist schief gelaufen. Die Bewerbung wurde nicht an Personio weitergegeben, bzw. Daten konnten nicht aus dem XML Feed abgerufen werden. Zusätzlich zu diesem Status Code gibt Personio noch einen konkreten Grund für das Scheitern der Anfrage aus. 

Status Codes sind universell und allgemeingültig deutbar. Finden Sie ein Liste aller von Personio ausgegebenen Status Codes hier.

Nachdem eine Antwort an den Klienten gesendet wurde, ist die Kommunikation abgeschlossen. Der Server ruht und wartet, bis er eine weitere Anfrage erhält. Wenn der Klient eine weitere Anfrage sendet, startet der Prozess von Neuem. 
 

 

Datenformate

Anfragen und Antworten im Rahmen der Personio API Schnittstelle, laufen über die Datenformate JSON und XML. 

JSON (JavaScript Object Notation) ist ein einfach strukturiertes Datenformat, welches auf der Programmiersprache Javascript beruht.

JSON bietet einen einfachen Standard für die Kodierung von Daten. Das Format speichert Daten strukturiert und in menschen- wie maschinenlesbarer Form. Dazu verwendet es Schlüssel-Wert-Paare und eine Formatierung mit geschweiften Klammern.

Sehen Sie nachfolgend ein Beispiel einer POST Anfrage, wobei z.B. "company_id" ein Schlüssel ist und "12345" der dazugehörige Wert.

{

"company_id": "12345", 

"access_token": "234ec563407665bc23000", 

[...] 

"first_name": "Franz-Alois", 

[...] 

}

Das Datenformat XML erfüllt ähnliche Anforderungen wie JSON. Ein anschauliches Beispiel für die Programmiersprache XML (Extensible Markup Language) erhalten Sie in Ihrem Personio XML Feed. 

Über den Header "Content-Type" informieren Klient und Server, in welchem Datenformat ihr Body geschrieben ist. Über den Header "Accept" erklärt der Klient, welches Datenformat er für Antworten des Servers akzeptiert, bzw. lesen kann. Wenn der Server das akzeptierte Datenformat nicht liefern kann, sendet er eine Fehlermeldung zurück. 

 

Die Personio Recruiting API 

Über die Personio Recruiting API können Sie Bewerbungen in Personio einspielen (POST) und offene Stellen abrufen (GET). Ihre Zugriffsdaten, welche Sie für jede Anfrage benötigen, finden Sie unter Einstellungen > API > Zugriffsdaten. Hier liegen sowohl Ihre Company ID als auch Ihr Recruiting API-Zugriffstoken: 

Screen_Shot_2018-09-18_at_16.07.41.png

 

Stellen aus Personio abrufen

Rufen Sie über eine GET Anfrage Informationen Ihrer veröffentlichten Stellen aus Ihrem XML Feed ab und binden Sie diese in Ihre Webseite ein. Die zugrunde liegende URL ist meinaccount-jobs.personio.de/xml. Weitere Informationen, Vorteile und technische Hintergründe zum XML Feed finden Sie hier.

Nachdem Ihre Stellen auf Ihrer Karriereseite angezeigt werden, müssen die eingehenden Bewerbungen über Anfrage und Antwort in Personio eingespielt werden:

Screen_Shot_2018-09-17_at_07.38.54.png

 

Bewerbungen in Personio einspielen

Um eine POST Anfrage nach Personio zu senden, verwenden Sie die folgende URL: https://api.personio.de/recruiting/applicant.

Obligatorisch benötigte Parameter für den Body der POST Anfrage sind: 

  • company_id (zu finden unter: Einstellungen > API > Zugriffsdaten
  • access_token (zu finden unter: Einstellungen > API > Zugriffsdaten
  • job_position_id (zu finden unter: meinaccount-jobs.personio.de/xml)
  • first_name (übermittelt über die Bewerbermaske)
  • last_name (übermittelt über die Bewerbermaske)
  • email (übermittelt über die Bewerbermaske)

Hinweis: Wir empfehlen die job_position_id automatisch aus dem aktivierten XML Feed zu ziehen (GET) und in die POST Anfrage zu integrieren. 

Des weiteren akzeptiert Personio optionale Parameter, z.B. 

  • birthday (übermittelt über die Bewerbermaske) oder 
  • documents (übermittelt über die Bewerbermaske)

Hinweis: Die Dokumente des Bewerbers können Sie entweder in einem sogenannten array gesammelt, oder einzeln einspielen. Finden Sie weitere Details dazu hier

 

Zudem können Sie Werte für all Ihre unter Einstellungen > Recruiting > Bewerber individuell angelegten Bewerberattribute über die API in Personio einspielen. Sie knüpfen dafür über den API Attributsnamen an das Bewerberattribut an. Diesen finden Sie im Editiermodus des Bewerberattributs:

Screen_Shot_2018-09-18_at_16.55.01.png

 

Des Weiteren haben Sie die Möglichkeit den Kanal zu übergeben, über welchen die Bewerbung eingegangen ist. 

Integrieren Sie dafür den Parameter recruiting_channel_id in Ihre POST Anfrage. Die ID des Kanals finden Sie unter Einstellungen > Recruiting > Kanäle

Screen_Shot_2018-09-18_at_17.12.46.png 

Eine komplette Liste aller Parameter, sowie zusätzliche Informationen dazu finden Sie in unserem Developer Hub.

 

Hinweis: Ein Entwickler braucht circa 1-2 Tage um eine API Integration zu implementieren. 

Finden Sie weitere Informationen zu der Personio Anwesenheits-API und der Personio Personaldaten-API hier: 

Einrichtung der Anwesenheits-API

Datenzugriff auf die Personaldaten-API

Haben Sie Fragen? Anfrage einreichen

0 Kommentare

Zu diesem Beitrag können keine Kommentare hinterlassen werden.