OAuth 2.0 Integratie met Bullhorn

De Bullhorn REST API biedt partners een eenvoudige maar krachtige manier om interactie te hebben met het Bullhorn-systeem. Deze API maakt gebruik van HTTP-verzoeken en standaard datastructuren, waardoor het toegankelijk is vanuit veel programmeertalen en bijzonder geschikt is voor mobiele applicaties en toepassingen die gebruikmaken van de nieuwste webtechnologieën. In deze blog bespreken we hoe je kunt starten met de Bullhorn REST API, inclusief de OAuth 2.0 autorisatieprocedure en het gebruik van access tokens om veilige API-aanroepen te doen.

Kort antwoord: Bullhorn gebruikt OAuth 2.0. Je vraagt OAuth-sleutels aan via het Bullhorn Resource Center, bepaalt met loginInfo het juiste datacenter, haalt een autorisatiecode op, wisselt die om voor een access token — geldig gedurende tien minuten — en logt daarmee in op de REST API voor een BhRestToken. Met een refresh token vernieuw je de sessie zonder opnieuw te autoriseren.

Hoe krijg je toegang tot de Bullhorn REST API?

Bullhorn gebruikt OAuth 2.0 als autorisatiemechanisme voor de REST API. Om toegang te krijgen tot de API, moeten Bullhorn-klanten OAuth-sleutels verkrijgen door een supportticket aan te maken via het Bullhorn Resource Center. Een geldige OAuth 2.0 API-sleutel bevat de volgende gegevens:

• redirect_uri: De URI van de locatie van je applicatie die aan Bullhorn is opgegeven bij registratie.
• client_id: Een door Bullhorn gegenereerde ID die jouw account identificeert.
• client_secret: Het wachtwoord voor je applicatie om in het systeem te authentiseren.

Hoe bepaal je het juiste Bullhorn-datacenter?

Bij gebruik van de Bullhorn REST API is het belangrijk om het juiste datacenter te bepalen voor je gebruiker. Dit kan worden gedaan door een GET-verzoek te sturen naar rest-services/loginInfo met de API-gebruikersnaam. Als je de correcte URL’s niet gebruikt, krijg je een 307-redirect naar het juiste datacenter. Zorg ervoor dat je code deze redirect kan verwerken. De API-gebruikersnaam is informatie die je van Bullhorn ontvangt nadat je bent aangesloten.

GET https://rest.bullhornstaffing.com/rest-services/loginInfo?username={API_Username}

Hoe verkrijg je een autorisatiecode?

Voordat je toegang kunt krijgen tot de API, moet je een autorisatiecode verkrijgen door de volgende URL te gebruiken, waarbij je de daadwerkelijke waarden voor de placeholders vervangt:

https://auth-{value_from_loginInfo}.bullhornstaffing.com/oauth/authorize?client_id={client_id}&response_type=code&action=Login&username={username}&password={password}&redirect_uri={optional redirect_uri}&state={recommended state value}

Stappen voor het Verkrijgen van een Autorisatiecode:

1. De gebruiker voert een geldige Bullhorn gebruikersnaam/wachtwoord combinatie in en klikt op de Login-knop.
2. Een servicevoorwaardenpagina wordt weergegeven.
3. De gebruiker klikt op de Akkoord-knop om de voorwaarden te accepteren.
4. De pagina wordt omgeleid naar de redirect_uri met een code-parameter in de URL. Deze code is de autorisatiecode die nodig is om een toegangstoken te verkrijgen.

Hoe verkrijg je een access token?

Je applicatie gebruikt de autorisatiecode om een toegangstoken te verkrijgen door een POST-verzoek te doen naar de volgende URL:

POST https://auth-{value_from_loginInfo}.bullhornstaffing.com/oauth/token?grant_type=authorization_code&code={auth_code}&client_id={client_id}&client_secret={client_secret}&redirect_uri={optional redirect_uri}

De respons bevat een toegangstoken dat je gebruikt in REST API /login-aanvragen om een Bullhorn-sessiesleutel en een basis REST URL te verkrijgen. Het toegangstoken is 10 minuten geldig.

Gebruik van een Refresh Token

Als Bullhorn je de mogelijkheid heeft gegeven om refresh tokens te genereren, bevat de respons ook een refresh token. Wanneer de Bullhorn-sessie verloopt, gebruik je een refresh token om een nieuw toegangstoken te verkrijgen zonder opnieuw te hoeven autoriseren. Het refresh token heeft geen vervaldatum, maar verloopt wanneer een nieuw toegangstoken en refresh token worden gegenereerd.

Hoe log je in bij de REST API?

De eerste aanroep die je maakt met de Bullhorn REST API is een login-aanroep naar de rest-services server voor het datacenter. Deze aanroep retourneert een sessiesleutel die je kunt gebruiken voor volgende verzoeken.

POST https://rest-{value_from_loginInfo}.bullhornstaffing.com/rest-services/login?version=*&access_token={xxxxxxxx}

Een succesvolle login-respons ziet er als volgt uit:

{
  "BhRestToken": "1234_5945926_32b73003-3b3a-4ebf-9a87-5894201b0ac3",
  "restUrl": "https://rest{swimlane#}.bullhornstaffing.com/rest-services/{corpToken}/"
}

Deze login-respons bevat een sessiesleutel genaamd BhRestToken en de basis URL voor volgende REST-aanroepen. Gebruik de sessiesleutel voor alle daaropvolgende verzoeken totdat de sessie verloopt.

Hoe doe je REST-aanroepen op Bullhorn?

Na het verkrijgen van een sessiesleutel kun je REST-aanroepen doen om gegevens op te halen of CRUD-operaties uit te voeren op de Bullhorn-server. Bijvoorbeeld, een verzoek om een specifieke kandidaat op te halen:

GET https://rest{swimlane#}.bullhornstaffing.com/rest-services/{corpToken}/entity/Candidate/{id}?BhRestToken={session_key}&fields=firstName,lastName,address

Aanmaken van een Entity

Een REST-aanroep om een nieuwe entiteit aan te maken lijkt op een GET-verzoek, maar is een HTTP POST en bevat veldwaarden voor de nieuwe entiteit in de body van het verzoek.

PUT https://rest{swimlane#}.bullhornstaffing.com/rest-services/{corpToken}/entity/Candidate?BhRestToken={session_key}

Conclusie

De Bullhorn REST API biedt een robuuste manier om met het Bullhorn-systeem te communiceren, en met behulp van OAuth 2.0 kan dit veilig en efficiënt gebeuren. Door de bovenstaande stappen te volgen, kun je succesvol integreren met Bullhorn en je recruitmentprocessen verbeteren.

Wil je van hier naar een werkende koppeling? Lees dan onze stap-voor-stap gids voor het integreren van Bullhorn met een vacaturewebsite, of bekijk hoe wij op deze API een veilige AI-assistent voor recruiters bouwden.

Voor meer informatie over het werken met de Bullhorn REST API en OAuth 2.0, bezoek de Bullhorn GitHub. Ook deze pagina is erg hulpvol