Für Agenturen und technische Dienstleister: Bewerbungen über die Concludis API 2.0 übertragen

Über die Concludis API 2.0 können Bewerbungen aus eigenen Bewerbungsformularen direkt an Concludis übertragen werden. In der Regel verwenden Kunden jedoch das Concludis-Bewerbungsformular und dessen Einbindungsmöglichkeiten.


Hinweis: Dieser Artikel beschreibt primär die Übertragung einer Bewerbung über die API 2.0. Die Funktionsweise der Global API beziehungsweise Partner API ist in vielen Punkten vergleichbar. Eine wesentliche Besonderheit ist dort unter anderem die Verwendung der globalen Projekt-ID gpid  für die Zuordnung.


Typischerweise besteht die Integration aus zwei Schritten:

  1. Formularaufbau über application/setup
  2. Übertragung der Bewerbung über application/apply

Die vollständige technische Dokumentation steht über den jeweiligen API-Account zur Verfügung. Dieser Artikel konzentriert sich auf den grundsätzlichen Ablauf und typische Ursachen, wenn eine Bewerbung nicht erfolgreich oder nicht vollständig korrekt verarbeitet wird.

Formularinformationen über application/setup abrufen

Bevor eine Bewerbung übertragen wird, sollte für das jeweilige Projekt die aktuelle Konfiguration des Bewerbungsformulars abgefragt werden.

Beispiel:

GET /api/2.0/de_DE/application/setup?project_id=12345

Für ein internes Bewerbungsformular kann beispielsweise zusätzlich angegeben werden:

GET /api/2.0/de_DE/application/setup?project_id=12345&is_internal=1

Der Setup-Endpoint liefert die für dieses Projekt relevante Formularstruktur.

Dazu können unter anderem gehören:

  • verfügbare Formularfelder
  • Pflichtfelder
  • Uploadfelder
  • Fragebögen und Screening-Fragen
  • Antwortmöglichkeiten
  • hinterlegte Arbeits- beziehungsweise Einsatzorte
  • projektspezifische Einstellungen

Das externe Bewerbungsformular sollte sich möglichst an dieser Konfiguration orientieren und diese nicht dauerhaft statisch nachbauen.

So können Änderungen am Bewerbungsformular oder am Projekt in Concludis auch vom externen System berücksichtigt werden.

Bewerbung über application/apply übertragen

Die ausgefüllte Bewerbung wird anschließend an den Apply-Endpoint übertragen:

POST /api/2.0/de_DE/application/apply

Der Request enthält abhängig von der jeweiligen Konfiguration beispielsweise:

  • Projekt
  • Arbeits- beziehungsweise Einsatzort
  • Bewerberstammdaten
  • Kontaktdaten
  • Adresse
  • Quelle
  • Antworten auf Fragen
  • Dokumente und Anlagen
  • weitere für den Bewerbungsweg benötigte Informationen

Bei erfolgreicher Verarbeitung wird die Bewerbung in Concludis angelegt und dem entsprechenden Projekt zugeordnet.

Die genaue JSON-Struktur sollte immer anhand des Tutorials des verwendeten API-Accounts umgesetzt werden.

Arbeits- und Einsatzort über location_ids übertragen

Ein Projekt kann in Concludis einem oder mehreren Arbeits- beziehungsweise Einsatzorten zugeordnet sein.

Die für das jeweilige Projekt hinterlegten Orte können über application/setup  ermittelt werden. Das externe Bewerbungsformular sollte diese Informationen verwenden und bei der Bewerbung den tatsächlich ausgewählten beziehungsweise zutreffenden Ort wieder an Concludis übergeben.

Die Übergabe erfolgt über location_ids .

Beispiel:

{  "project_id": 926,  "location_ids": [123],  "source_id": 15,  "candidate": {    "person": {      "birthDate": "1958-10-29",      "gender": "..."    }  } }

Dabei enthält location_ids  die ID beziehungsweise IDs der für die Bewerbung relevanten Locations.

Auch wenn eine Bewerbung technisch unter Umständen ohne location_ids  in Concludis angelegt werden kann, sollte auf die Übertragung nicht verzichtet werden.

Der Arbeits- beziehungsweise Einsatzort kann innerhalb von Concludis für weitere Prozesse relevant sein. Dazu gehören insbesondere:

  • Sichtrechte von Benutzern
  • Zuständigkeiten und Verantwortlichkeiten
  • weitere standortabhängige Prozesse innerhalb des Systems

Fehlt die Location, kann die Bewerbung daher zwar technisch vorhanden sein, intern aber nicht so verarbeitet oder den richtigen Personen angezeigt werden, wie es für das Projekt vorgesehen ist.

Für eine vollständige Integration sollte deshalb immer geprüft werden:

  1. Welche Locations liefert application/setup  für das Projekt?
  2. Welcher Ort wurde im externen Bewerbungsformular ausgewählt?
  3. Wird dessen ID anschließend über location_ids  an application/apply  zurückgegeben?

Die Location-IDs sollten dabei aus den für das Projekt bereitgestellten Daten übernommen und nicht unabhängig davon erzeugt oder statisch hinterlegt werden.

Interne und externe Bewerbungen

Concludis unterscheidet zwischen internen und externen Bewerbungswegen.

Eine Stelle kann beispielsweise ausschließlich intern veröffentlicht und bewerbbar sein.

Wird für ein solches Projekt eine externe Bewerbung übertragen, kann Concludis die Bewerbung ablehnen, obwohl das Projekt grundsätzlich existiert.

Daher sollten Setup und Apply für denselben Bewerbungsweg verwendet werden.

Für interne Bewerbungen ist insbesondere die entsprechende Kennzeichnung über is_internal  zu berücksichtigen.

Pflichtfelder und Formularlogik

Ein häufiger Grund für abgelehnte Bewerbungen sind fehlende oder nicht zur aktuellen Formularkonfiguration passende Pflichtfelder.

Wichtig ist dabei die Unterscheidung zwischen:

  • strukturierten Feldern des Bewerbungsformulars
  • Fragebögen beziehungsweise Screening-Fragen

Strukturierte Formularfelder können abhängig davon konfiguriert sein, ob es sich um eine interne oder externe Bewerbung handelt.

Ein Feld kann daher beispielsweise im externen Formular aktiviert sein, im internen Formular aber nicht.

Der Setup-Endpoint liefert diese Information.

Beispiel:

"ipt_availability_startdate_enabled": true

oder:

"ipt_availability_startdate_enabled": false

Wenn das externe System unterschiedliche interne und externe Bewerbungswege unterstützt, sollte deshalb auch der jeweilige Setup-Response verwendet werden.

Fragebögen und Screening-Fragen

Fragebögen sollten nicht fest in der Integration hinterlegt werden.

Die aktuell für das Projekt konfigurierten Fragen werden über application/setup  bereitgestellt.

Die Antworten werden anschließend beim Apply wieder an Concludis übertragen.

Beispiel für eine einzelne Antwort:

{  "id": 37,  "value": "Antwort" }

Bei einer Mehrfachauswahl können mehrere Werte übertragen werden:

{  "id": 41,  "values": [25, 29] }

Wichtig ist, die von application/setup  gelieferten IDs unverändert wiederzuverwenden. Die Integration sollte keine eigenen IDs erzeugen oder Annahmen über deren Format treffen.

Dokumente und Anlagen

Bewerberdokumente wie Lebenslauf oder Zeugnisse können zusammen mit der Bewerbung übertragen werden.

Je nach API-Struktur werden die Dateien Base64-codiert innerhalb des Requests übergeben.

Bei Problemen mit Anlagen sollten insbesondere folgende Punkte geprüft werden:

  • Ist das Attachment vollständig?
  • Ist der Inhalt korrekt Base64-codiert?
  • Ist der vorgesehene Dokumenttyp beziehungsweise das Uploadfeld korrekt?
  • Entspricht die Struktur dem aktuellen API-Tutorial?
  • Werden leere Attachment-Objekte übertragen?

Leere oder unvollständige Attachment-Strukturen sollten nicht mitgesendet werden.

Quellenzuordnung

Wenn die Bewerbung über ein externes Karriereportal übertragen wird, sollte auch die ursprüngliche Bewerbungsquelle korrekt mitgegeben werden.

Je nach Bewerbungsweg kann dies über eine Source-ID oder über zusätzliche Tracking-Metadaten erfolgen.

Bei Multiposting über GOhiring gelten zusätzliche Anforderungen. Wenn die Bewerbung zuvor über einen GOhiring-Tracking-Link auf das externe Bewerbungsformular gelangt ist, müssen die entsprechenden Tracking-Informationen bei der Rückübertragung erhalten bleiben.

Hierfür kann beispielsweise gohiring_meta  relevant sein.

Die Quellenzuordnung sollte deshalb immer zusammen mit dem vollständigen Bewerbungsweg betrachtet werden.

Typische Ursachen bei einer fehlgeschlagenen oder unvollständigen Übertragung

Wenn application/apply  eine Bewerbung nicht annimmt oder die Bewerbung anschließend nicht wie erwartet verarbeitet wird, sollten zunächst folgende Punkte geprüft werden:

  1. Ist das Projekt aktuell für den verwendeten Bewerbungsweg bewerbbar?
  2. Wird intern oder extern korrekt unterschieden?
  3. Wurde zuvor der aktuelle application/setup  für dieses Projekt abgerufen?
  4. Sind alle aktuell erforderlichen Pflichtfelder enthalten?
  5. Stimmen die übermittelten Frage-IDs und Antwortoptionen mit dem Setup überein?
  6. Ist das JSON syntaktisch korrekt?
  7. Enthält der Request leere oder unvollständige Objekte?
  8. Sind Anlagen korrekt aufgebaut und codiert?
  9. Wird die richtige Projekt-ID verwendet?
  10. Wird die zum Projekt beziehungsweise zur Bewerbung gehörende Location über location_ids  übertragen?
  11. Werden gegebenenfalls benötigte Quellen- oder Tracking-Informationen mitgegeben?

Gerade bei einer Bewerbung, die zwar erfolgreich angelegt wurde, anschließend aber nicht bei den erwarteten Benutzern erscheint oder nicht den vorgesehenen Verantwortlichkeiten folgt, sollte die übertragene Location geprüft werden.

Fehler trotz HTTP 200

Bei der API 2.0 kann ein Request technisch mit HTTP 200 beantwortet werden und trotzdem einen fachlichen Fehler enthalten.

Beispiel:

{  "errors": [    {      "code": 5001,      "subcode": 410,      "msg": "..."    }  ] }

Eine Integration sollte daher nicht ausschließlich den HTTP-Status auswerten.

Zusätzlich sollte immer geprüft werden, ob die Antwort ein Fehlerobjekt enthält.

Beispiel: Projekt ist nicht bewerbbar

Eine typische Fehlermeldung kann sinngemäß lauten:

Eine Bewerbung auf das Stellenangebot ist nicht oder nicht mehr möglich.

Diese Meldung ist bewusst allgemein gehalten.

Sie kann beispielsweise auftreten, wenn:

  • ein Projekt abgelaufen ist
  • eine Bewerbungsfrist erreicht wurde
  • das Projekt nicht mehr bewerbbar ist
  • eine ausschließlich interne Stelle als externe Bewerbung angesprochen wird

Bei der Fehlersuche sollten deshalb immer die Veröffentlichungs- und Bewerbbarkeitseinstellungen des Projekts zusammen mit is_internal  geprüft werden.

Wenn eine Übertragung nicht nachvollziehbar fehlschlägt

Für eine technische Prüfung durch den Concludis Support sind möglichst folgende Informationen hilfreich:

  • betroffene Concludis-Instanz
  • Projekt-ID
  • gegebenenfalls übertragene Location-ID
  • Zeitpunkt der Übertragung
  • vollständiger Request beziehungsweise JSON-Body
  • vollständige API-Antwort
  • Information, ob es sich um eine interne oder externe Bewerbung handelt
  • gegebenenfalls Application-ID einer bereits angelegten Bewerbung

Passwörter, Access-Tokens oder andere Zugangsdaten sollten dabei nicht übermittelt werden.

Mit einem vollständigen Request lässt sich in der Regel wesentlich schneller nachvollziehen, an welcher Stelle die Verarbeitung abweicht.

API-Tutorial als technische Referenz

Die genaue Struktur von application/setup  und application/apply  sowie alle verfügbaren Felder sind im Tutorial des jeweiligen API-Accounts dokumentiert.

Da sich Bewerbungsformulare, Locations und verwendete Felder zwischen verschiedenen Concludis-Instanzen und Projekten unterscheiden können, sollte das Tutorial zusammen mit dem tatsächlichen Setup-Response immer die Grundlage der Implementierung sein.

Hat das Ihre Frage beantwortet? Vielen Dank für Ihr Feedback Ihr Feedback konnte leider nicht gespeichert werden. Bitte versuchen Sie es später nocheinmal.