Website koppelen
Opmerking: het aanmaken van een website koppeling vereist beheerders rechten binnen ForceFlow.
ForceFlow's api maakt het mogelijk om jouw website met ForceFlow te koppelen, maar ook om vacatures aan te maken of statistische informatie op te halen.
Om een website te koppelen zijn er 2 mogelijkheden om de meest recente gepubliceerde vacatures op te halen:
- Polling: elk half uur wordt door ForceFlow een lijst met gepubliceerde vacatures klaargezet (in een cache).
- Webhook: zodra een vacature gepubliceerd, aangepast of offline gezet is, wordt er een post-request gestuurd naar de gedefinieerd webhook
Met polling heb je dus een lijst met vacatures die gemiddeld 15 minuten minder recent zijn. In de meeste gevallen is dit prima, echter wanneer je meteen de wijzigingen op je website wilt zien dan zul je de webhook koppeling moeten gebruiken.
Let op: je kunt een website niet rechtstreeks aan de ForceFlow api koppelen. Zorg ervoor dat je aan de server kant eens per half uur de vacatures ophaalt en deze 'lokaal' opslaat.
Instellen van de koppeling
ForceFlow ondersteunt maximaal10 websites per bedrijf. Om naar meerdere websites te publiceren ga je naar het Organisatie tabblad en selecteer je de opzoeklijst 'API koppeling. Hier kun je de extra websites aanzetten, hun namen wijzigen en de volgorde aanpassen.
Om gebruik te kunnen maken van een koppeling moet je deze eerst activeren. Ga naar het tabblad koppelingen in de bedrijfsinstellingen. Hier zie je nu het volgende:
- Dit is de key (token) die nodig is voor autorisatie, deze kun je zichtbaar maken door op het oog (2) te klikken.
- Door op het oog te klikken wordt de key zichtbaar. Deze is standaard niet zichtbaar i.v.m. beveiliging.
- Je kunt de key vernieuwen. Wanneer je deze vernieuwt zullen bestaande koppelingen niet meer werken,
- Om de koppeling daadwerkelijk te gebruiken vink je 'Gebruik Website' aan. Wanneer deze niet aanstaat is de api niet bereikbaar.
- Hier bepaal je de scope van de key. De scope zijn de endpoints waar de key toegang tot heeft.
- Hier kun je de webhook definiƫren en testen.
- Dit is een link naar de api documentatie.
Let op: zorg ervoor dat je de key (token) niet openbaar maakt. Wanneer dit wel gebeurt genereer een nieuwe key zoals beschreven staat in optie (3).
Zodra je de koppeling hebt geactiveerd (4) kun je vacatures gaan publiceren. Ga hiervoor naar het overzicht van de vacatures en open een vacature. Je kunt dan deze publiceren door op de knop 'Start publiceren' te klikken. De vacature wordt nu in de status gepubliceerd geplaatst. Vervolgens klik je de website aan waar je op wil publiceren:
De vacature is nu gepubliceerd en zal staan in de lijst van gepubliceerde vacatures als deze opgevraagd wordt. Om een vacature van de lijst van gepubliceerde vacatures te verwijderen zijn er verschillende mogelijkheden:
- Deselecteer het vinkje 'Website'.
- Klik op de knop 'Stop publiceren'
De gepubliceerde vacature verdwijnt ook wanneer de vacature daadwerkelijk verwijderd of gearchiveerd wordt.
Rate limits
Op alle requests zitten rate limits om de stabiliteit van de api te garanderen. Deze limiet geldt per bedrijf. Per type request zit een verschillende limiet op:
- GET: maximaal 60 request per uur per endpoint.
- POST: maximaal 200 requests per uur per endpoint.
In de response header geeft het systeem de limiet en de overgebleven requests terug in de headerkeys: X-Post-Ratelimit-Limit en X-Post-Ratelimit-Remaining
Ga je over het maximum heen dan krijg je als response 429 (too many requests).
Autorisatie
De api maakt gebruik van een autorisatie key (token). Deze key moet worden toegevoegd aan de request header met als naam Authorization.
Voorbeeld van een request header:
{ Accept: application/json Authorization: ad7bf119-6c2b-4007-977e-9f012752fb54 }
Polling van vacatures
Met de request get jobs kun je een lijst van gepubliceerde vacatures ophalen (deze wordt eens per half uur ververst). In de header van de request kan je nog de volgende keys gebruiken:
language | De taal waarin de vacature moet worden gepubliceerd (bijvoorbeeld nl). Standaard staat deze op auto, dit is de standaardtaal aangeven op de vacature. Als je gebruik maakt van meerdere talen binnen 1 vacature dan heb je ook de keuze voor all. Dit heeft wel consequenties voor de opmaakt van de response (je krijgt dan een array met verschillende talen per vacature terug). |
codes | Standaard geeft de api de omschrijvingen van de opzoeklijsten terug, maar wanneer codes=true in de header wordt gezet dan wordt de interne code gebruikt. |
lookup-objects | Wanneer deze op true staat, dan wordt de opzoekwaarde als een object teruggegeven:
|
fields | Hier kun je aangeven tot welke velden je het resultaat wilt beperken, bijvoorbeeld: title,description. |
Webhooks
Om meteen de wijzigingen van de vacatures op je website te tonen, kun je gebruik maken van webhooks. Er zijn drie typen webhooks:
- publish: wordt verstuurd zodra een vacature is gepubliceerd op je website.
- update: wordt verstuurd wanneer een vacature inhoudelijk gewijzigd wordt.
- unpublish: wordt verstuurd wanneer de vacature niet meer de status gepubliceerd heeft, miet meer toegewezen is aan de website of als de vacature verwijderd/gearchiveerd wordt.
In de header van de POST request stuurt ForceFlow de key mee, waarmee je het request kunt controleren. De body van het request bestaat uit de vacature gegevens (onder het veld job, het type webhook en het id van de vacature. Bij unpublish wordt niet de vacature gegevens meegestuurd.
Kandidaat toevoegen
Met de request post candidate kun je een kandidaat toevoegen aan een vacature of open laten solliciteren. Het enige verplichte veld is naam, de overige velden zijn optioneel.
Om een kandidaat in proces op een vacature te zetten met je het id van de vacature meegeven in het veld jobId, wanneer dit veld ontbreekt wordt de kandidaat als open sollicitatie aangemaakt.
Velden worden via validatie gecontroleerd op correctheid. Wanneer velden binnen het request niet juist zijn dan zal de api reageren met een foutmelding (400) en de reden.
Bestanden moeten worden omgezet naar base64 om te kunnen worden toegevoegd aan de request (Er zijn diverse online converters om dit te testen).
Tip: ForceFlow kan voor iedere vacature een sollicitatie pagina tonen. Door deze functie hoef je geen eigen formulier te maken wat vaak veel tijd kost (validatie, bestand uploaden, testen)
Lees de documentatie om de module sollicitatie pagina te gebruiken.