Für Agenturen und Technische Dienstleister: Karriereseite und Stellenanzeigen über die Concludis API 2.0 anbinden

Mit der Concludis API 2.0 können Stellenangebote aus Concludis auf einer individuell entwickelten Karriereseite oder Stellenbörse dargestellt werden.


Die API richtet sich unter anderem an Webagenturen und technische Dienstleister, die Stellenlisten und Stellenanzeigen in das Design und die Struktur einer Unternehmenswebsite integrieren möchten.


Für den Zugriff ist ein entsprechender API-Account erforderlich. Über diesen Account steht auch das ausführliche API-Tutorial zur Verfügung. Dort sind alle verfügbaren Endpoints, Parameter und Rückgabewerte im Detail beschrieben.


Dieser Artikel beschreibt deshalb bewusst nur den grundsätzlichen Aufbau einer Stellenbörse.


Grundprinzip

Die Stellenangebote werden über den Projects-Endpoint aus Concludis abgerufen:


GET /api/2.0/de_DE/projects

Ein typischer Abruf für eine öffentliche Stellenbörse kann beispielsweise so aussehen:


GET /api/2.0/de_DE/projects
    ?published=2
    &applicable=2
    &show[0]=jobad_structured
    &show[1]=locations
    &page=1
    &ipp=100

Die API liefert eine Liste von Projekten zurück. Über die Parameter lässt sich bestimmen, welche Projekte berücksichtigt und welche zusätzlichen Informationen ausgegeben werden.


Veröffentlichte und bewerbbare Stellen

Für den Aufbau einer Stellenbörse sind insbesondere die Parameter published  und applicable  wichtig.


published  bestimmt den Veröffentlichungszustand:


0 = keine Einschränkung
1 = intern oder extern veröffentlicht
2 = extern veröffentlicht
3 = intern veröffentlicht

applicable  bestimmt, ob eine Bewerbung auf das Projekt möglich ist:


0 = keine Einschränkung
1 = intern oder extern bewerbbar
2 = extern bewerbbar
3 = intern bewerbbar

Für eine klassische öffentliche Karriereseite wird daher in der Regel mit


published=2
applicable=2

gearbeitet.


Damit werden Projekte berücksichtigt, die extern veröffentlicht und für externe Bewerbungen freigegeben sind.


Für eine interne Stellenbörse kann entsprechend mit den internen Zuständen gearbeitet werden.


Wichtig ist die Unterscheidung zwischen Veröffentlichung und Bewerbbarkeit: Eine Stelle kann grundsätzlich veröffentlicht sein, ohne dass über diesen Bewerbungsweg aktuell eine Bewerbung möglich ist.


Stellen nach Stellenbörse filtern

Wenn innerhalb einer Concludis-Instanz mehrere Stellenbörsen verwendet werden, kann die Ausgabe über boards[]  eingeschränkt werden.


Beispiel:


boards[0]=318

Damit werden nur Projekte berücksichtigt, die dieser Stellenbörse zugeordnet sind.


Ohne einen Board-Filter können alle Projekte berücksichtigt werden, die den übrigen angegebenen Kriterien entsprechen.


Die verfügbaren Stellenbörsen und deren IDs sind kundenspezifisch.


Welche Daten sollen ausgegeben werden?

Über den Parameter show[]  kann der Detailgrad der Antwort erweitert werden.


Für den Aufbau einer Karriereseite sind insbesondere folgende Werte relevant.


Strukturierte Stellenanzeige

show[0]=jobad_structured

Damit wird die Stellenanzeige in strukturierter Form ausgegeben.


Das Projekt enthält dann unter anderem:


jobad.containers
jobad.tracking_codes
jobad.google_for_jobs_code

jobad_structured  eignet sich besonders dann, wenn die Agentur die Stellenanzeige selbst aufbauen und die einzelnen Bestandteile in das eigene Layout integrieren möchte.


Vollständiges Markup

Alternativ kann die Stellenanzeige als vollständiges Markup angefordert werden:


show[0]=jobad_full_markup

Die Antwort enthält dann:


jobad.full_markup

Dieser Weg ist sinnvoll, wenn die bereits zusammengestellte Stellenanzeige möglichst vollständig übernommen werden soll.


Welche Variante verwendet wird, hängt daher von der geplanten Integration ab:


jobad_structured
→ einzelne Bestandteile der Anzeige stehen strukturiert zur Verfügung

jobad_full_markup
→ vollständiges Markup der Stellenanzeige wird geliefert

Standorte

Mit


show[1]=locations

werden die vollständigen Location-Objekte der jeweiligen Projekte ausgegeben.


Diese Daten können beispielsweise für die Anzeige von Arbeitsorten oder für eigene Standortfilter verwendet werden.


Weitere show-Parameter

Darüber hinaus stehen weitere Erweiterungen zur Verfügung:


evaluators

liefert die dem Projekt zugeordneten Bewerter.


usergroups

liefert die zugeordneten Benutzergruppen.


ba_extended

liefert erweiterte Informationen zur Veröffentlichung bei der Bundesagentur für Arbeit.


indeed_extended

liefert erweiterte Informationen zur Veröffentlichung bei Indeed.


Für eine normale öffentliche Stellenbörse werden diese Informationen in der Regel nicht benötigt.


Die vollständige Beschreibung aller show[] -Optionen befindet sich im API-Tutorial.


Kundenindividuelle Projektfelder

Neben den Standardfeldern kann eine Concludis-Installation zusätzliche kundenindividuelle Projektfelder enthalten.


Diese werden als custom_fields  innerhalb der Projektdaten ausgegeben.


Solche Felder können beispielsweise als


  • Freitextfeld
  • Auswahlfeld

angelegt sein.


Sie können zusätzliche Informationen enthalten, die der Kunde für seine Stellenanzeigen oder die Struktur seiner Stellenbörse verwendet.


Ein mögliches Beispiel wäre ein Projektfeld für Benefits, Kategorien oder weitere kundenindividuelle Merkmale.


Da Aufbau und Inhalt dieser Felder vom jeweiligen Kunden abhängen, sollte die Integration die tatsächlich gelieferten custom_fields  der jeweiligen Concludis-Instanz berücksichtigen.


Es sollte nicht davon ausgegangen werden, dass bei allen Kunden dieselben Custom Fields oder dieselben Werte vorhanden sind.


Aufbau der Stellenübersicht

Aus der Projektliste kann die Agentur die gewünschte Stellenübersicht erstellen.


Typischerweise werden dabei beispielsweise verwendet:


  • Projekt-ID
  • Stellentitel
  • Standort
  • Unternehmen
  • Veröffentlichungsinformationen
  • kundenindividuelle Projektfelder

Welche Informationen tatsächlich dargestellt oder als Filter verwendet werden, kann entsprechend der Karriereseite individuell entschieden werden.


Darstellung einer einzelnen Stellenanzeige

Für die Detailseite kann entweder mit den bereits aus der Projektliste erhaltenen Daten gearbeitet oder ein einzelnes Projekt separat abgefragt werden.


Beispiel:


GET /api/2.0/de_DE/projects/project
    ?id=12345
    &show[0]=jobad_structured

Alternativ kann auch hier beispielsweise jobad_full_markup  verwendet werden.


Damit kann die Agentur entscheiden, ob die Anzeige aus den strukturierten Bestandteilen selbst aufgebaut oder das vollständige Markup verwendet werden soll.


Pagination

Bei einer größeren Anzahl von Projekten sollte der Projects-Endpoint seitenweise abgefragt werden.


Hierfür stehen die Parameter


page
ipp

zur Verfügung.


Beispiel:


page=1
ipp=100

Anschließend werden die weiteren Seiten abgefragt, bis keine weiteren Projekte zurückgegeben werden.


Die geeignete Seitengröße kann abhängig vom Umfang der Projektdaten und den verwendeten show[] -Parametern gewählt werden.


Empfohlener technischer Aufbau

Für eine Karriereseite empfiehlt sich eine serverseitige Synchronisation.


Ein typischer Aufbau ist:


Concludis API
      ↓
Server der Karriereseite
      ↓
lokale Datenhaltung / Cache
      ↓
Stellenbörse und Stellenanzeigen

Der Server der Karriereseite ruft die Projektdaten regelmäßig aus Concludis ab und speichert die benötigten Informationen zwischen.


Die Besucher der Karriereseite greifen anschließend auf diese Datenbasis zu und lösen nicht bei jedem Seitenaufruf eine vollständige API-Abfrage aus.


Dies reduziert die Anzahl der API-Aufrufe und ermöglicht kurze Ladezeiten auf der Karriereseite.


Deeplinking und eigene URLs

Eine individuell entwickelte Karriereseite verwendet häufig eigene URLs für Stellenanzeigen.


Beispiel:


https://www.example.com/karriere/jobs/softwareentwickler

Für die Verbindung mit Concludis muss trotzdem eine eindeutige Zuordnung zwischen der Concludis Projekt-ID und der jeweiligen Stellenanzeige möglich sein.


Ein technisches URL-Schema könnte beispielsweise so aussehen:


https://www.example.com/karriere/job/12345

Die Website kann diese URL anschließend intern auf eine sprechende URL weiterleiten:


/job/12345
      ↓
/karriere/jobs/softwareentwickler

Entscheidend ist, dass anhand der von Concludis übergebenen Projekt-ID eindeutig die richtige Stellenanzeige aufgerufen werden kann.


Bewerbungsweg

Die Darstellung der Stellenanzeige und der eigentliche Bewerbungsweg sind getrennt voneinander zu betrachten.


Je nach Konfiguration kann nach Klick auf „Bewerben“ beispielsweise


  • ein Concludis Bewerbungsformular
  • ein anderer in Concludis konfigurierter Bewerbungsweg
  • ein extern bereitgestelltes Bewerbungsformular

aufgerufen werden.


Der konfigurierte Bewerbungsweg sollte deshalb bei der Integration berücksichtigt und nicht unabhängig davon aus einzelnen Projektdaten nachgebaut werden.


Mehrsprachige Stellenbörsen

Die API 2.0 unterstützt sprachabhängige Abfragen über den jeweiligen Locale im API-Pfad.


Beispiel Deutsch:


/api/2.0/de_DE/projects

Für weitere Sprachen wird der entsprechende Locale verwendet.


Damit können auch mehrsprachige Stellenbörsen und Stellenanzeigen umgesetzt werden.


API-Tutorial als technische Referenz

Dieser Artikel soll den grundsätzlichen Aufbau einer Stellenbörse erklären und ersetzt nicht die technische API-Dokumentation.


Die vollständige Dokumentation steht über den jeweiligen API-Account zur Verfügung.


Dort finden sich unter anderem:


  • Authentifizierung
  • vollständige Beschreibung der Endpoints
  • alle Filterparameter
  • verfügbare show[] -Parameter
  • Request- und Response-Strukturen
  • Feldbeschreibungen
  • weitere technische Beispiele

Für die konkrete Implementierung sollte daher immer das Tutorial des API-Accounts als technische Referenz verwendet werden.


Hinweis zur API 1.0

Für neue Integrationen ist die Concludis API 2.0 zu verwenden.


Die frühere API 1.0 und darauf basierende Integrationsanleitungen sind deprecated und sollten nicht mehr als Grundlage für neue Stellenbörsen oder Karriereportal-Integrationen verwendet werden.

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.