Mijn Communities
Help

Recruiting API - Domain model and concepts

28-01-2022 11:26 (Bijgewerkt op 24-06-2024)
  • 0 Antwoorden
  • 0 kudos
  • 976 Weergaven

 

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

customFields

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

customField1

 

 

string

customField2

 

 

string

customField3

 

 

string

customField4

 

 

string

customField5

 

 

string

customField6

 

 

string

customField7

 

 

string

customField8

 

 

string

customField9

 

 

string

customField10

 

 

string

customField11

 

 

string

customField12

 

 

string

customField13

 

 

string

customField14

 

 

string

customField15

 

 

string

customField16

 

 

string

customField17

 

 

string

customField18

 

 

string

customField19

 

 

string

customField20

 

 

string

customField21

 

 

string

customField22

 

 

string

customField23

 

 

string

customField24

 

 

string

customField25

 

 

string

customField26

 

 

string

customField27

 

 

string

customField28

 

 

string

customField29

 

 

string

customField30

 

 

string

 

Vacancies DRAFT

⚠️ This is a draft endpointVacancy 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

pic1.pngpic2.pngpic3.png

 

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.