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
gpidfür die Zuordnung.
Typischerweise besteht die Integration aus zwei Schritten:
- Formularaufbau über
application/setup - Ü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:
- Welche Locations liefert
application/setupfür das Projekt? - Welcher Ort wurde im externen Bewerbungsformular ausgewählt?
- Wird dessen ID anschließend über
location_idsanapplication/applyzurü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:
- Ist das Projekt aktuell für den verwendeten Bewerbungsweg bewerbbar?
- Wird intern oder extern korrekt unterschieden?
- Wurde zuvor der aktuelle
application/setupfür dieses Projekt abgerufen? - Sind alle aktuell erforderlichen Pflichtfelder enthalten?
- Stimmen die übermittelten Frage-IDs und Antwortoptionen mit dem Setup überein?
- Ist das JSON syntaktisch korrekt?
- Enthält der Request leere oder unvollständige Objekte?
- Sind Anlagen korrekt aufgebaut und codiert?
- Wird die richtige Projekt-ID verwendet?
- Wird die zum Projekt beziehungsweise zur Bewerbung gehörende Location über
location_idsübertragen? - 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.