Recruiting API - Domain model and concepts

[#1]

• Candidates
• Technical flow
• Candidate data
• Vacancies DRAFT
• Vacancy data
• ID scan

This API is intended for recruiting systems and allows them to get the data needed for the recruiting process and send the candidate to be hired.

Candidates

Technical flow

The candidate endpoint is asynchronous:

1. The recruiting sends in the new hire or contract change.
2. Youforce will
   1. Validate the incoming data
   2. Trigger Id Scan (optional)
   3. Start a process based on configuration of the customer
3. The recruiting system checks if the hire has been accepted.

Steps 3 is critical. The process is only accepted by Youforce when the status is 'Completed'. It is the responsibility of the recruiting system to check if the hire is successfully trigged by based on the entered data. There are no user feedback mechanisms in Youforce that inform a hiring manager that the new hire has not been accepted by Youforce.

Candidate data

Property	Description	Mandatory	Example	Data type
candidateID	The ID of the candidate in the recruiting system. This field is available as free field in the Core for Reporting purpose.	Yes	0001	string
PersonData	Fields related to the person
	PersonalDetails: last name, first names, date of birth, etc
	PhoneNumbers: list of phone numbers	One is mandatory
	emailAdress: Private email address to contact the candidate.	Yes	candidate@private.com	string
	Addresses: list of addresses
PersonalDetails	Fields related to personal data
	lastNameAtBirth: The last name at birth of the candidate. Also the family name.			string
	lastNameAtBirthPrefix: The prefix of the last name at birth.			string
	knownAs: The name which is used by the candidate as his first name.			string
	initials: The initials of the candidate.			string
	firstNames: The official given names of the candidate.			string
	lastName: The last name the candidate is currently using.			string
	gender: The gender of the candidate.		(0) Not known (1) Male (2) Female (9) Not applicable To use 0 and 9 values, they must be configured in the core system.	string
	birthDate: Date of birth of the candidate.			DateTime
	birthPlace: The place of birth of the candidate.			string
	birthCountry: The country of birth of the candidate.			string
	primaryNationality: The nationality of the candidate.			string
	titlePrefix: The formal title which will be used as a prefix before the name.			string
	titleSuffix: The formal title which will be used as suffix after the name.			string
	maritalStatus: The marital status of the candidate.			string
	lastNamePreference: A code that indicates the preferred last name of the employee. for instance last name at birth last name partner last name partner + last name at birth last name at birth + last name partner			string
	lastNamePartner: The partner last name.			string
	partnerNamePrefix: The prefix of the partner last name.			string
	socialSecurityNumber: Social Security Number of the candidate.			string
phoneNumber	details of the phone number
	type: home, mobile		home	string
	number		+ 31 0624829858	string
Address	Fields related to the address of the candidate
	type: home, postal		home	string
	streetName: Street name		Wamberg	string
	number: House number		69	string
	NumberAdditional: additional number		34	string
	locationDescription: location			string
	postalCode: Postal code		1083 CV	string
	city: City		Amsterdam	string
	region: Region			string
	country: Country		The Netherlands	string
ApplicationDetails	Fields related with the application
	vacancyNumberHR: Vacancy number in the HR Core systems. With this field the core system can check if the position is still open.		001	string
	vacancyNumberATS: Vacancy number in the Applicant Tracking System. This field is available as free field for Reporting purpose.		1001	string
	offerApproveDate: Date that the offer is approved in the ATS system. It is the date that the recruitment process ends and the onboarding of the new employee can start.		01-01-2021	DateTime
NewEmployement	Fields related to the new employement
	payrollClient: The Id of payroll client in the core systems.		B2020	string
	payrollCompany: The Id of payroll company in the core system.	Yes	C2020	string
	collectiveLaborAgreement: Id of the collective labor agreement.		CAO01	string
	hireDate: Proposed hire date of the Candidate.	Yes	01-01-2021	DateTime
	endDate: If the contract is for a given time, this contains the end date of the employment.		31-12-2021	DateTime
	contractType: Type of the contact.	Yes	01	string
	probationPeriod: Indicates if a probation period is applied to the contract.			boolean
	probationPeriodDuration: Duration of the probation period.			string
	probationPeriodEnddate: End date of the probation period.		31-03-2021	DateTime
	employeeType: Type of employment like Internal employee, contractor, etc.	Yes	001	string
	organizationalUnit: Id of the organization unit of employment.	Yes	OU1	string
	jobProfile: Job profile of the employment.	Yes	JP1	string
	establishmentUnit: The logical code of location or establishment unit where the work is performed mainly in accordance with the contractual arrangement.		EU1	string
	amountOfHours: Amount of working hours.	Yes	40	string
	Salary: Fields related to the salary.
	OtherBenefits: List of other benefits.
Salary	Fields related to the salary
	salaryType: Type of salary			string
	SalaryPeriodicity			string
	SalaryAmount			string
	ContractSalary			string
	SalaryScale			string
	SalaryGrade			string
	RPSFactor			string
	HourlyRateAmount			string
	HourlyRateScale			string
	hourlyRateGrade			string
Benefit	Fields to describe other benefits
	benefitCode: Code of the benefit.		BEN01	string
	value: Value of the benefit.		1000	string
CurrentEmployment	Fields related to current employement if exists.
	PersonCode: Code of the person in the existing contract.		1000250	string
	employmentCode: Code of the employment in the existing contract.		1	string

Vacancies DRAFT

⚠️ This is a draft endpoint. Vacancy data cannot be exposed at this moment. Please reach out to our community for more info. 

Vacancy data

Property	Description	Example	Data type
VacancyCode	Unique vacancy number in the HR Core Self Service. This job request number is unique within the tenant.	VAC0012	string
Title	Title of the Vacancy	Case manager	string
organizationUnit	Logical code of the organization unit	HR01	string
payrollCompany	Logical code of the company	B01	string
recruitmentChannel	Channel in which the recruitment systems will publish the job request.	extern	string
jobProfile	Logical code of the Job profile	CMAN	string
jobLevel	Required level of the job like instance Junior, Medior or Senior	Medior	string
jobFamily	Logical code of the Job Family	HR	string
employeeType	Type of employee	Intern	string
amountHoursWeek	Amount of hours a week	40	int
contractType	Contract type	temporal	string
contractualDuration	Duration of the contract. Only relevant contract type is temporal.	1 year	string
establismentUnit	The logical code of the location or establishment unit where the work is performed, mainly in accordance with the contractual arrangement.	AMS	string
numberOfPositionsRequired	Total number of requested positions	5	int
ApprovalDate	Approval date of the job request	2020-12-20	DateTime
startDate	Start date of the job request	2021-01-01	DateTime
endDate	End date of the job request	2021-04-01	DateTime
owner	Manager of the job request	J. Janssen	string
ownerEmailAddress	Email address of the owner of the job request	j.jansen@visma.com	string
RecruitmentReason	Indicates the reason for this new position. For instance because it is new position, extension of existing position or replacement of an existing person on a position.	Replacement	string
SalaryIndication	Indication for the salary, for instance a range like: 1500 - 1800 euro or a maximum: max 2000 euro or a scale: Scale 10	Schale 10	string
ExperienceLevel	ExperienceLevel	4-6	string
Extensions	List of additional fields configured in the HSS and the API
	key		string
	value		string

ID scan

Customers can enable a Visma|Youserve ID Scan as part of their Recruiting API connections. This will increase data quality and ensure efficient administrative onboarding process. This is optional and needs to be enabled per customer. 

The ID scan will complement or overwrite the data send by the recruiting system

The ID scan will be triggered once the candidate has been received from our system. The candidate will receive an invite to scan his identity document and complete his data.

The following data will be captured from the ID document:

• Birth names (incl. prefix) 
• Initials
• BSN  
• Nationality
• Birthdate
• Birthplace
• Gender
• Doc type
• Document number
• Document Registration Date
• Document Expiry Date

The following data will be entered manually be the employee:

• Firstname to use + prefix
• Lastname to use + prefix
• Bankaccount (IBAN - minimal validation)
• Home address (street, number, postal, place, country)
• Partner last name + prefix 
• Title for
• Title after

ID Scans retention policy

Successfully processed IDs will be forwarded as attachments in the triggered Hire or Contract change process in Self Service. The Self-Service retention & archiving policies are applicable for these attachments. 

The service responsible for scanning the IDs will retain IDs as follows: 

• Successfully processed ID will be removed after 24 hours. An ID is processed when the Recruiting API has retrieved the scan from the ID scan service.
• Unprocessed ID will be removed after 2 weeks. So when the recruiting API was unable to fetch the ID scan for 2 weeks, the IDs will be automatically removed.