Een API-koppeling met een ATS laat twee systemen automatisch gegevens en acties uitwisselen via een vastgelegde technische interface. In plaats van handmatig kandidaten, vacatures of statussen over te typen, vraagt het ene systeem gegevens op bij het andere systeem of stuurt het wijzigingen door. Voor een betrouwbare koppeling zijn duidelijke afspraken nodig over welke gegevens beschikbaar zijn, wie toegang krijgt, welk systeem leidend is, hoe fouten worden afgehandeld en hoe wijzigingen in de API worden beheerd.
Wat is een API?
API staat voor Application Programming Interface. Een API beschrijft hoe software met andere software kan communiceren. Bij een ATS kan dat bijvoorbeeld betekenen dat een werken-bij-site vacatures ophaalt, een assessmentplatform een kandidaat ontvangt of een HR-systeem gegevens krijgt nadat iemand is aangenomen.
De kennisbank over essentiële ATS-koppelingen laat zien dat integraties vooral waardevol zijn wanneer ze dubbel invoerwerk voorkomen en processen beter beheersbaar maken. Een API is een veelgebruikte technische manier om zulke integraties te realiseren.
Een API is geen kant-en-klare koppeling. De API biedt mogelijkheden om gegevens op te vragen of te wijzigen. Een concrete integratie gebruikt een deel van die mogelijkheden om een proces uit te voeren.
Welke gegevens kun je via een ATS-API uitwisselen?
Welke gegevens beschikbaar zijn, verschilt per systeem. Veelvoorkomende objecten in recruitment zijn:
- vacatures en publicatiestatussen;
- kandidaten en contactgegevens;
- sollicitaties en procesfasen;
- interviews en afspraken;
- beoordelingen en assessments;
- afdelingen, locaties en gebruikers;
- documenten of verwijzingen naar documenten;
- statussen rond aanname en onboarding.
Niet ieder extern systeem heeft al deze gegevens nodig. Een assessmenttool hoeft bijvoorbeeld meestal geen volledig kandidaatdossier te ontvangen. Naam, e-mailadres, assessmenttype en een unieke referentie kunnen voldoende zijn.
REST en HTTP zijn veelgebruikte bouwstenen
Moderne zakelijke API’s werken vaak via HTTP. Een systeem stuurt een verzoek naar een zogenoemd endpoint en ontvangt een antwoord, meestal in een gestructureerd formaat zoals JSON.
De OpenAPI Specification is een leveranciersneutrale standaard waarmee HTTP-API’s beschreven kunnen worden. De specificatie maakt zichtbaar welke endpoints bestaan, welke invoer ze verwachten en welke antwoorden mogelijk zijn. Dat helpt bij documentatie, ontwikkeling en testen.
Voor een ATS-integratie is goede API-documentatie belangrijk. Zonder duidelijke beschrijving van velden, rechten, foutcodes en versies wordt een koppeling moeilijker te bouwen en te onderhouden.
Authenticatie bepaalt wie toegang krijgt
Een ATS bevat persoonsgegevens en andere gevoelige informatie. Daarom moet een API kunnen vaststellen welk systeem een verzoek doet en wat dat systeem mag.
Veel API’s werken met tokens of andere vormen van authenticatie. Het uitgangspunt moet zijn dat een koppeling alleen toegang krijgt tot de functies en gegevens die nodig zijn voor het proces.
Dat sluit aan bij de security-audit van een ATS. Daarin is het advies om actieve API-koppelingen, rechten en sleutels periodiek te controleren en ongebruikte toegang te verwijderen.
OWASP benoemt in zijn API Security Top 10 onder meer gebrekkige autorisatie en gebroken authenticatie als belangrijke API-risico’s. Dat maakt duidelijk waarom een API-koppeling niet alleen technisch moet werken, maar ook zorgvuldig moet worden beveiligd.
Eenrichtingsverkeer en tweerichtingsverkeer
Niet iedere integratie hoeft twee kanten op te werken. Een eenrichtingskoppeling kan bijvoorbeeld aangenomen kandidaten vanuit het ATS naar het HR-systeem sturen.
Bij tweerichtingsverkeer stuurt het andere systeem ook informatie terug. Een HRIS kan bijvoorbeeld afdelingen, functies of hiring managers naar het ATS sturen. De ATS-HRIS-koppeling is daar een voorbeeld van.
Tweerichtingsverkeer maakt processen flexibeler, maar vraagt om duidelijkere afspraken. Wanneer dezelfde informatie in beide systemen gewijzigd kan worden, moet vaststaan welk systeem bij een verschil leidend is.
Webhooks voorkomen onnodig opvragen
Een integratie kan steeds opnieuw vragen of er iets is veranderd. Dat heet polling. Een andere methode is dat het ATS zelf een bericht verstuurt wanneer een gebeurtenis plaatsvindt. Zo’n automatisch bericht wordt vaak een webhook genoemd.
Denk aan een melding wanneer een kandidaat wordt aangenomen. Het ontvangende systeem kan daarna via de API de benodigde gegevens ophalen.
Dit kan efficiënter zijn dan iedere paar minuten alle records controleren. Tegelijkertijd moet ook bij webhooks worden gecontroleerd of berichten betrouwbaar worden afgeleverd en of een mislukte verwerking opnieuw wordt geprobeerd.
Foutafhandeling hoort bij het ontwerp
Een koppeling moet niet alleen onder ideale omstandigheden werken. Het HR-systeem kan tijdelijk niet bereikbaar zijn, een verplicht veld kan ontbreken of een kandidaat kan al bestaan.
Leg daarom vooraf vast:
- welke foutcodes worden verwacht;
- hoe vaak een mislukte actie opnieuw wordt geprobeerd;
- waar fouten worden gelogd;
- wie een waarschuwing ontvangt;
- hoe een fout handmatig kan worden hersteld;
- hoe dubbele verwerking wordt voorkomen.
Een integratie zonder monitoring kan technisch actief lijken terwijl gegevens al dagen niet meer goed worden verwerkt.
Versiebeheer voorkomt onverwachte uitval
API’s veranderen. Er komen nieuwe velden bij, oude functies verdwijnen en beveiligingsmethoden kunnen worden aangepast. Controleer daarom hoe een ATS API-versies beheert en hoe wijzigingen worden aangekondigd.
Een volwassen integratie gebruikt niet alleen endpoints, maar houdt ook rekening met versies en afhankelijkheden. Test wijzigingen eerst in een testomgeving wanneer dat mogelijk is.
Maak daarnaast duidelijk wie eigenaar is van de koppeling. De recruiter hoeft niet te weten hoe iedere API-call werkt, maar de organisatie moet wel weten wie verantwoordelijk is als de gegevensstroom stopt.
Test complete recruitmentscenario’s
Een succesvolle technische API-test bewijst nog niet dat het hele proces werkt. Test daarom herkenbare recruitmentscenario’s.
Maak bijvoorbeeld een vacature aan, laat die publiceren, registreer een kandidaat, verplaats de kandidaat naar een volgende fase en controleer of alle aangesloten systemen de juiste informatie ontvangen.
Test ook uitzonderingen zoals:
- ontbrekende contactgegevens;
- een dubbel kandidaatprofiel;
- een ingetrokken sollicitatie;
- een kandidaat die na aanname toch niet start;
- een tijdelijk onbereikbaar extern systeem.
Checklist voor een ATS-API-koppeling
- Beschrijf eerst het recruitmentproces dat je wilt ondersteunen.
- Bepaal welke gegevens werkelijk moeten worden uitgewisseld.
- Leg vast welk systeem per gegeven leidend is.
- Gebruik zo beperkt mogelijke toegangsrechten.
- Documenteer endpoints, velden en foutcodes.
- Regel logging, monitoring en waarschuwingen.
- Test normale processen en uitzonderingen.
- Maak afspraken over API-versies en wijzigingen.
- Controleer periodiek of de koppeling en toegang nog nodig zijn.
