RecruitAnywhere API

RecruitmentTechnologies provides a web-service for organisations that want to manager their jobs on job boards and social media across Europe from one system.

The RecruitAnywhere API makes it easy to enrich existing applications with job advertising capabilities.

• Post, update, remove and automatically re-post jobs on a large selection of job boards
• Jobs are posted within minutes
• Auto-expire jobs per job board
• Seamless integration with leading recruitment software: Carerix, Connexys, OTYS, PeopleXS, etc
• Multiple languages per job

If you are an Application Tracking System, you will need to familiarise yourself with these API/XUI specs.

The RecruitmentTechnologies help desk can help you getting started with interfacing with RecruitAnywhere.

The easiest and preferred way to integrate RecruitAnywhere into your ATS is the XUI (eXternal User Interface). This plugin is a ready made user interface and handles all the API calls to RecruitAnywhere.

RecruitmentTechnologies builds interfaces to Job Boards using the API of the Job Boards, so if you are a Job Board and want RecruitmentTechnologies to build an interface to you contact our helpdesk.

Supported Integration Scenarios

Depending on your preference you can select any of the supported integration scenarios.

To address this RecruitmentTechnologies provides a plugin for your ATS that presents the user with the list of job boards / channels to post to and takes care of all the communications with the RecruitAnywhere API.

Pro:

• Easy to setup
• Plugin maintained by RecruitmentTechnologies
• Best possible integration with RecruitmentTechnologies API
• Optionally provides for single sign on

Your ATS only needs to provide two things for the XUI plugin:

• A web location to retrieve the job in XML format, see example

• An iframe to load the XUI plugin, see documentation

To make the user experience even more seamless you can optionally go for the single sign on:

• Your server requests an access token for the user from RecruitmentTechnologies (once a day, or per request)
• Your server generates the iframe page for the XUI plugin with that access token

IMPORTANT: the XUI can only be used if your ATS can provide all the mandatory fields for a job. Please discuss the setup with our helpdesk

The RecruitAnywhere system has to retrieve the xml data, this must be done via a standard single url with only one variable per client: the job id.

For example: https://www.test.com/jobs?jobid=[JobID] or example

• [JobID] is the variable job number which refers to the specific job within the ATS.
• This jobid must be unique per client/database.
• This url must contain all the xml data for the specific job, i.e. all the mandatory fields must be available within this xml.
• The job XML must be in RecruitAnywhere XML format

Each ‘Jobs’ XML file can contain one ‘JobPosition’ tag.

The ‘JobPosition’ XML contains the following tags:

• JobDetails
• Contact
• Channels
• JobContentVersion

JobPosition tag

JobTitle and JobTitleDescription fields

The JobTitle and JobTitleDescription fields are used in complement to each other. On some job boards job title is a look-up value, for these job boards you have to supply a value in the JobTitle fields. Currently job boards like werk.nl, Nationale Vacaturebank.nl, VDAB.be and Vacature.com/JobsCareer.be/Reference.be all require a look-up value for JobTitle.

The system will use JobTitleDescription whenever possible, even if a JobTitle value is supplied. On some job boards it will supply both using the look-up value as a search criteria and the JobTitleDescription as the free text version.

JobDetails tag

JobRequirements section

JobOffer

JobLocation

Contact

* Default the system uses the contact details stored from the consultant/branch records. If you specify contact

details with the job posting, the system will use those instead of the details stored with the consultant/branch.

Channels

XML Example

<?xml version="1.0" encoding="UTF-8"?>
<Jobs>
	<JobPosition status="active" id="123" onerrorcancelsave="n">
		<JobDetails>
			<JobTitle><![CDATA[200777]]></JobTitle>
			<JobTitleDescription><![CDATA[Teammanager in Almere]]></JobTitleDescription>
			<JobBranch><![CDATA[OVERI]]></JobBranch>
			<JobCategory><![CDATA[COMM]]></JobCategory>
			<JobLevel><![CDATA[PROF]]></JobLevel>
			<JobSummary><![CDATA[]]></JobSummary>
			<JobCompanyProfileName><![CDATA[Streetwise Direct Dialogue B.V.]]></JobCompanyProfileName>
			<JobCompanyProfile><![CDATA[De specialist en marktleider op het gebied van digital dialogue donateurwerving.]]></JobCompanyProfile>
			<ClientName><![CDATA[]]></ClientName>
			<ClientRegistrationNumber><![CDATA[]]></ClientRegistrationNumber>
			<ClientStreetAddressName><![CDATA[]]></ClientStreetAddressName>
			<ClientStreetAddressNo><![CDATA[]]></ClientStreetAddressNo>
			<ClientStreetAddressNoExt><![CDATA[]]></ClientStreetAddressNoExt>
			<ClientZipCode><![CDATA[]]></ClientZipCode>
			<ClientCity><![CDATA[]]></ClientCity>
			<!-- ClientCountry: ISO 2 char -->
			<ClientCountry><![CDATA[]]></ClientCountry>
			<JobDescription><![CDATA[Op dit moment zijn wij opzoek naar een Teammanager voor deur tot deur
                verkoop Algemene functieomschrijving van een Teammanager: Als teamleider geef je
                leiding aan een team van ongeveer 20 tot 30 studenten (tussen de 16 en 22 jaar) die
                parttime zullen werken, dit zal deur tot deur verkoop zijn. Je bent als Teammanager
                zelf verantwoordelijk om je eigen team te werven. Daarnaast begeleidt je, stimuleer
                je en motiveer je je team van wervers. Ook ben je verantwoordelijk voor de
                personeelsplanning, administratie, het plannen en aansturen van de werfacties en de
                logistieke organisatie. Je bent 80% van de tijd bezig op straat om je wervers te
                coachen, motiveren en trainen. De overige tijd zal je werkzaamheden verrichten op
                kantoor, hierbij kun je denken aan: het voeren van evaluatiegesprekken,
                sollicitatiegesprekken, eventueel exitgesprekken, het invoeren van scores, maken van
                rapportages, etc. De werktijden voor een Teammanager voor deur tot deur werver zijn
                van 13.00 tot 22.00 uur. ]]></JobDescription>
			<JobContractType><![CDATA[Direct Hire]]></JobContractType>
			<JobHours>40</JobHours>
			<JobParttime>2</JobParttime>
			<JobRequirements>
				<Education><![CDATA[HBO]]></Education>
				<Education><![CDATA[MBO]]></Education>
				<EducationDirection><![CDATA[COMM]]></EducationDirection>
				<EducationDirection><![CDATA[OV]]></EducationDirection>
				<Experience>4</Experience>
				<JobRequirementsDescription><![CDATA[-HBO werk- denkniveau; - Je vind het leuk om zowel
                    vanuit kantoor als buiten in het veld op operationeel gebied te managen; -Je
                    bent commercieel; -Je bent flexibel; - Een zelfstandige werker; - Assertief; -
                    Geen 9 tot 5 mentaliteit. ]]></JobRequirementsDescription>
			</JobRequirements>
			<JobOffer>
				<JobOfferDescription><![CDATA[Een uitdagende functie binnen een enthousiaste en trendy
                    organisatie]]>.</JobOfferDescription>
				<Salary>
					<SalaryValueFrom>1750</SalaryValueFrom>
					<SalaryValueTo>1750</SalaryValueTo>
					<SalaryDescription><![CDATA[Good salary]]></SalaryDescription>
				</Salary>
			</JobOffer>
			<JobLocation>
				<LocationCity><![CDATA[AMSTERDAM]]></LocationCity>
				<LocationRegion><![CDATA[FL]]></LocationRegion>
				<LocationZipCode><![CDATA[1011 AB]]></LocationZipCode>
			</JobLocation>
		</JobDetails>
		<Contact>
			<BranchName><![CDATA[85-4]]></BranchName>
			<Consultant/>
			<FullName><![CDATA[Marlon Brandenburg]]></FullName>
			<Email><![CDATA[almere@example.com]]></Email>
			<WebSite><![CDATA[www.example.com]]></WebSite>
			<Phone><![CDATA[035 - 5280333]]></Phone>
			<AddressName><![CDATA[Joop van den Endplein]]></AddressName>
			<AddressNo><![CDATA[1]]></AddressNo>
			<AddressNameNoExt><![CDATA[a]]></AddressNameNoExt>
			<ZipCode><![CDATA[1217WJ]]></ZipCode>
			<City><![CDATA[Hilversum]]></City> 
		</Contact> 
		<Channels applydirectlink="" clearchannelsbeforeupdate="n" advertid="3456"/>
	</JobPosition>
</Jobs>

Setting up the XUI + single sign on

To make sure our clients will be logged in automatically we provide a simple SSO procedure.

The XUIAccessToken must be retrieved with a GET Method via the url with a Basic authentication (username and password):

dev: GET: https://appsdev.knollenstein.com/servlet/KnGetAccessTokenServlet?permissions=xui

prod: GET: https://apps.knollenstein.com/servlet/KnGetAccessTokenServlet?permissions=xui

The response message will be:

<Token id=”f6a930d7-9904-42c6-9d7b-80b3dec6ccb8″ />

Your ATS needs to generate an iframe using this:

The following needs to be provided by your ATS in the iframe:

• XUIUserID: RecruitmentTechnologies Username

• XUIVid: Jobid of the job the user is working on and which corresponds with the XML job id

• XUILocale: The country/language locale code. for example “nl_NL”

• XUIAccessToken: the RecruitmentTechnologies access token which retrieved

The token will be valid for 24 hours after receiving the token, also more then one token can be used at once. You can choose to either get tokens for each user e.g. once every 24 hours or retrieve a token with every request.

In the xui you can delete a job, but you'll have to open the plugin.

Since a lot of ATS system can archive/delete a job on a higher level in the system, it's also possible to delete a job via the following HTTP GET in combination with a basic authentication of the client credentials:

DEV: https://appsdev.knollenstein.com/servletngc/KnDeleteVacancyServlet?vid=123

PROD: https://apps.knollenstein.com/servletngc/KnDeleteVacancyServlet?vid=123

The parameter 'vid' is the specific job id you want to delete.

Note: The whole job wille be deleted

The response will be a http status 200 with the following response:

• On loading, the XUI checks if all mandatory fields are filled in. If fields are missing an error will be displayed, so it could be more user friendly to do the check for the mandatory fields beforehand.
• In most ATS systems you can close an entire job. This means the job is being deleted/archived out of the system en will be deleted from there own website. To save some time, you can make sure when archiving the job to send RecruitmentTechnologies a Delete call via Http Post request. This way the consultant does not need to open the XUI to delete the job from all selected job boards / channels
• If needed RecruitmentTechnologies can post the job status to a web service whenever a job is posted, updated or deleted on a channel. This way your system stays in sync with the Knollenstein job posting status.
• The xml Data contains a lot of criteria fields. To keep the RecruitAnywhere system in sync with the criteria lists in your ATS RecruitmentTechnologies prefers to have access to a web service to retrieve those criteria lists.

Knollenstein can optionally define business rules to automatically switch channels on and off for a job.

So if for example you always want 5 free channels selected if channel ‘WEBSITE’ was selected by the user the business rules will automatically select those 5 channels. If a week later the user decides to remove the job from channel ‘WEBSITE’ it will also be automatically removed from those 5 channels.

The XUI is by far the easiest way to integrate RecruitAnywhere into your ATS. If somehow this is not possible, RecruitAnywhere can also by integrated using:

- 2 times a day loading of all your jobs using HTTP GET

- both your UI and the RecruitAnywhere UI ('FUI')

To make onboarding of your clients as easy as possible, we (RT) prefer the following process:

1. RT gets the client details from the client
2. RT checks the application link on the client's website (do we generate or get it from the ATS?)
3. RT creates the default users and sets up the client
4. RT requests an API key from the ATS or the client
5. RT uses the API key to retrieve from your ATS the organisational units of the client and the lookup lists (job categories, regions etc.)
6. RT auto-maps the client's lists to the job boards lists
7. RT schedules an instruction with the client

If possible please make sure RT can import the client's organisational units and lookup lists using e.g. an API key.

For more information about integrating RecruitAnywhere into your ATS, please contact our helpdesk via support@recruitmenttechnologies.com.

For information about subscriptions and rates, please contact our sales department at +31(0)35-5280333 or via sales@recruitmenttechnologies.com.