Application Programming Interface (API)

11. Februar 2021
  • Doku

Einführung

Die REST-API von PitchYou ermöglicht es Drittsystemen,

  • den WhatsApp-Kanal von PitchYou für Bewerbungen zu nutzen,
  • die über diesen Kanal generierten Bewerbungen in die eigene Software zu übernehmen und
  • nach der Bewerbung mit den Kandidaten über WhatsApp zu chatten.

Die technische Dokumentation der API finden Sie hier: https://api.pitchyou.de/docs

 

Autorisierung und Aufrufe

Alle API-Aufrufe sind als REST-Methoden implementieret, die über die URL https://api.pitchyou.de erreichbar sind.

Es wird OAuth2 Autorisierung verwendet. Für die Aufrufe von API-Methoden ist ein access token notwendig. Dieser token wird über die API-Methode (POST): /token abgerufen. Für den Abruf sind eine client_id und ein client_secret notwendig. Beide Parameter werden Ihnen als Nutzer der API vom PitchYou zur Verfügung gestellt.

 

Szenario 1: Integration von PitchYou-Interviews als Bewerbungskanal in die Stellenausschreibungen des ATS

1.

PitchYou stellt verschiedene Interview-Templates für verschiedene Jobs zur Verfügung. Diese Templates legen fest, wie die WhatsApp-Bewerbung abläuft, welche Fragen gestellt und welche Medien (Bild, Video, Dokumente) abgefragt werden.

(GET) /api/jobtemplates/v1/gettemplates liefert eine Liste (Array) aller zur Verfügung stehender Interview-Templates als Liste von JobTemplateDto zurück.

Der Schlüssel für ein Interview-Template findet sich in einem JobTemplateDto als templateKey die Beschreibung findet sich in descriptions.

2.

Im angebundenen ATS können diese Interview-Templates (z. B. als Dropdown-Liste) bei der Ausschreibung von Stellen angeboten werden, um für jede Ausschreibung festzulegen, welches Interview bei einer späteren Bewerbung über WhatsApp durchlaufen werden soll.

3.

Die durch das angebundene ATS generierte Stellenausschreibung sollte einen entsprechenden Button oder Link enthalten, der zur Nutzung der WhatsApp-Bewerbung motiviert. Z. B. "Jetzt einfach per WhatsApp bewerben". Es ist erfolgsversprechender, wenn der Link oder Button mit einem WhatsApp-Logo (Wiedererkennungswert) versehen wird.

Die Absprung URL ist wie folgt aufgebaut.

https://{client_id}.pitchyou.de/go/{external_job_id}?jkey={templateKey}&title={jobtitle}&utm_source={utm_source}&utm_medium={utm_medium}&utm_campaign={utm_campaign}&utm_content={utm_content}

Dabei ist:

client_id (mandatory): Die eindeutige Bezeichnung des Mandanten (siehe Token Erzeugung bei der Autorisierung)

external_job_id (mandatory): Ein beliebiger Job-Identifier aus dem angebundenen ATS. Er dient zur eindeutigen Zuordnung eines Bewerberprofils zur einer Stellenausschreibung im ATS und wird beim späteren Abruf der Profile in der Struktur ProfileDto zurückgegeben (durchgereicht).

templateKey (optional): Gibt an welches Interview-Template für den Job zu benutzen ist. Wenn dieser Parameter fehlt, wird das Standard-Interview für den Mandanten ausgeliefert.

title (optional): Gibt den Job-Titel an. Dieser wird im WhatsApp-Interview verwendet, um den Bewerber noch einmal mitzuteilen, für welchen Job er sich gerade bewirbt.
 
utm_source (optional): Wird beim späteren Abruf der Profile in der Struktur ProfileDto zurückgegeben (durchgereicht).
 
utm_medium (optional): Wird beim späteren Abruf der Profile in der Struktur ProfileDto zurückgegeben (durchgereicht).
 
utm_campaign (optional): Wird beim späteren Abruf der Profile in der Struktur ProfileDto zurückgegeben (durchgereicht).
 
utm_content (optional): Wird beim späteren Abruf der Profile in der Struktur ProfileDto zurückgegeben (durchgereicht).
 
4.
Die Stellenanzeige kann nun vom angebundenen ATS veröffentlicht werden.
 
5.
Wenn ein Kandidat in einer Stellenanzeige die angegebene Ziel-URL aufruft, startet das WhatsApp-Interview. Es wird die angegebene Interview-Vorlage (templateKey) für den Interview-Ablauf herangezogen. Nach Abschluss des Interviews steht ein PitchYou-Bewerber-Profil zur Verfügung.

Szenario 2: Integration von Bewerbungen, die über den PitchYou-Bewerbungskanal eingegangen sind

Integration der über PitchYou eingegangenen Bewerbungen in das ATS

1.

Die PitchYou-Bewerber-Profile können jederzeit vom angebundenen ATS abgerufen werden (pull).

(GET) /api/applicant/v1/profiles

Die Methode liefert eine Liste (Array) von Bewerberprofilen (ProfileDto) zurück.

Das Wichtigste zum Aufbau des ProfileDto:

  • Jede Bewerbung wird eindeutig durch die profileId identifiziert.
  • Die Interview-Fragen und Antworten finden sich im Array steps wieder
  • Jeder step kann Medien-Daten (Bild, Dokument, Video) enthalten (attachments array)
  • Eine Bewerbung kann weitere Medien-Daten in den Felder cv und profileImage enthalten.
  • Die aus der Bewerbungs-URL eins-zu-eins durchgereichten Parameter finden sich in: utmSource, utmMedium, utmCampaign, utmContent, jobTemplateKey und externalReferenceId (enthält die external-job-id).

Wie können die Mediendaten abgerufen werden?

Zu jeder Media-Datei in ProfileDto gibt es die Parameter:

mimeType, fileName, mediaId, downloadUri

Pro Media-Datei muss die Methode

(GET) /api/media/v1/download/{profileId}/{mediaId}

aufgerufen werden. Sie liefert die Media-Datei als octet-stream zurück.

2.

Die abgerufenen Bewerberprofile und alle dazugehörigen Parameter können im ATS gespeichert werden. Die Zuordnung zum entsprechenden Job im ATS erfolgt über die external-job-id, die mit dem Aufruf des Interviews durchgereicht wurde.

Der erfolgreiche Abruf eines oder mehrerer Bewerberprofile aus PitchYou muss über den Aufruf

(POST) /api/applicant/v1/confirm

quittiert werden.

Als Parameter erhält die Methode ein Array von profileIds.

4.

Das Bewerber-Profil steht nun im ATS zur Verfügung und der Recruiting-Prozess im ATS kann durchlaufen werden.

Szenario 3: Integration der Möglichkeit, nach der Bewerbung mit Kandidaten zu chatten

1.

Im Verlauf des Recruiting-Prozesses müssen oft Rückfragen an den Bewerber gestellt werden. Der Bewerber soll dazu aufgefordert werden, weitere Dokumente hochzuladen oder ein Termin für ein Vorstellungsgespräch soll vereinbart werden. Der Recruiter möchte für diese Kommunikation am besten den bestehenden WhatsApp-Kanal nutzen.

2.

Um das fortgeführte Chatten mit einem Bewerber zu starten muss das ATS bei PitchYou einen Chat-Token anfordern

Über die Methode

(POST) /api/chattoken/v1

mit den Parametern profileId und recruiterName erhält das ATS einen Token für die weitere Kommunikation als string zurück.

profileId (mandatory) ist die aus dem Profilabruf eindeutige Id eines Bewerberprofils.

recruiterName (optional) kann benutzt werden, um im nachfolgenden Chat die Nachrichten des Recruiters mit seinem Namen zu personalisieren. Der Bewerber weiß dann, welche Person gerade mit ihm kommuniziert.

3. Das ATS muss nun die PitchYou-Chat-UI aufrufen bzw. integriert anzeigen. Dazu wird die PitchYou-Chat-URL

https://chat.pitchyou.de/{token}

verwendet.

Es gibt drei Möglichkeiten der Integration:

  • Aufruf der URL aus dem ATS in einem separaten Browser-Tab oder Browser-Fenster
  • Integration in die Oberfläche des ATS über ein IFrame
  • Integration in die Oberfläche des ATS über ein Widget. Der zugehörige Content (css und javascript) wird von uns geliefert.

Um das Chat-UI zu testen steht eine freie Testumgebung unter https://test.pitchyou.chat/ zur Verfügung.

4.

Der Recruiter chattet nun über die PitchYou-Chat-UI mit dem Bewerber, ohne WhatsApp zu benutzen. Der Bewerber erhält alle Nachrichten des Recruiters per WhatsApp zugestellt. Er antwortet auch per WhatsApp. Die Antworten landen beim Recruiter in der PitchYou-Chat-UI.

Soll ein weiterer Chat mit einem anderen Bewerber oder später mit dem gleichen Bewerber gestartet werden, muss ein neues Chat-Token generiert werden.

Zurück

Navigation Schließen Suche E-Mail Telefon Kontakt Pfeil nach unten Pfeil nach oben Pfeil nach links Pfeil nach rechts Standort Externer Link Startseite Facebook LinkedIn Instagram