Knowledge base YouServe API's

  Swagger documentation The following swagger page gives an overview of the endpoints: WFM API Endpoints Classifications The endpoint r eturns a list of all classifications . GET https://api.youserve.nl/wfm/v1.0/ classifications   The valueList can be configured on different levels in HRCB; system   - The 1st level a property can be defined, this is the highest level. client  - The 2nd level, these items are defined on the tenant level and generally defined by the customer company   - The 3rd level, these items are defined on company level, meaning only relevant for the specific company the properties are defined for The company code is returned as part of the company type   Data mapping Property Description Example HR Core Business shortName short name of classification       fullName full name of the item       level Indicates the level in the core system where the item is configured (“client” level or “company” level).       validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A   Companies The endpoint GET companies gives a list of company versions of the tenant. GET https://api.youserve.nl/wfm/v1.0/companies    Retrieve 1 company by adding the id of the company: GET https://api.youserve.nl/wfm/v1.0/companies/<id>    Retrieve only records which that have changed within the provided date-time (UTC) range: GET https://api.youserve.nl/wfm/v1.0/companies?from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z . Format:  YYYY-MM-DDTHH:MM:SS.sssZ Data mapping Property Description Example HR Core Business id identifier of the company     mutkey shortName short name of the company     company code fullName full name of the company     company name validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A isDeleted           Cost centers The endpoint r eturns a list of all cost centers . GET https://api.youserve.nl/wfm/v1.0/ costcenters   The valueList can be configured on different levels in HRCB; system   - The 1st level a property can be defined, this is the highest level. client  - The 2nd level, these items are defined on the tenant level and generally defined by the customer company   - The 3rd level, these items are defined on company level, meaning only relevant for the specific company the properties are defined for The company code is returned as part of the company type   Retrieve only records which that have changed within the provided date-time (UTC) range: GET https://api.youserve.nl/wfm/v1.0/ costcenters ?from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z . Format:  YYYY-MM-DDTHH:MM:SS.sssZ   Data mapping Property Description Example HR Core Business shortName short name of cost center       fullName full name of the cost center       level Indicates the level in the core system where the item is configured (“client” level or “company” level).       validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A isDeleted           Employments The employee endpoint returns information about the employments registered in HRCB ("Medewerker > Contract").   https://api.youserve.nl/wfm/v1.0/employments   Retrieve 1 employment by adding the id of the employment. https://api.youserve.nl/wfm/v1.0/employments/<id>    Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/wfm/v1.0/employments? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   Data mapping Property Description Example HR Core Business id Employment id 12459897 49 Contract mutkey personCode The unique id assigned to the employee 32789 10519680 Persoon nummer personId The globally unique id assigned to an employee 12345678 7014 Uniek Persoonlijk ID (UPI) employeeCode The code of the employee or employment 12345 22 Medewerker code contractCode Code of the contract 1 91 Contract id costAllocation Deprecated       dischargeDate The end date or discharge date of the employee. This is always an "up to and including" date. In case of no values the field will not be returned as part of the response body 2018-12-31 10520479 Geplande laatste datum indienst note: calculated field: [Geplande laatste datum indienst] = [Datum uitdienst] - 1 day   Datum uitdienst = fieldnr 40 hireDate Date of hire for the employment 2017-05-01 39 Datum in dienst originalHireDate The first hire date or original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee 2010-10-01 308 Datum in dienst organisatie Enddate Enddate of contract 2022-12-31 7226 Afloopdatum company  (deprecated)  (deprecated) Unique identifier of company the where contract is concluded 001 18 Bedrijfscode companyCode Unique identifier of company the where contract is concluded 001 18 Bedrijfscode location The location of where the employment is being performed 789 75 Vestiging site The location at which the employment is being fulfilled Vestiging 1 7449 Vestiging costCenter The cost center under which the employment is registered 012 53 Kostenplaats classification Cost allocation of the employment 123 474 Classifiecatiekenmerk 1 employmentType Code of the employment type 4 7393 Type medewerker jobProfile The job profile code 9909 DEV 97 Functie organizationUnit The organization unit id 1234567 ZKH 6000 Mutkey organisatorische eenheid emailAddresses Business email address   Business b.user@example.com 7212 E-mailadres phoneNumbers List of phone numbers and types Business +3188 345 67 89 7374 Telefoonnummer intern workingAmount Working amount of the employment. amountOfWork: numeric value representing the work amount 40   465 Uren periode periodOfwork: indicates the period for which amountOfWork and unitOfWork are defined Week FourWeeks Month Quarter 463 Dagen/uren per Week Maand validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A isDeleted Provide the active/inactive status of the record in the core system. False       Employment types The endpoint r eturns a list of all employment types . https://api.youserve.nl/wfm/v1.0/employmenttypes    The valueList can be configured on different levels in HRCB; system   - The 1st level a property can be defined, this is the highest level. client  - The 2nd level, these items are defined on the tenant level and generally defined by the customer company   - The 3rd level, these items are defined on company level, meaning only relevant for the specific company the properties are defined for The company code is returned as part of the company type   Data mapping Property Description Example HR Core Business shortName short name of employment type 001     fullName full name of the employment type Internship     level Indicates the level in the core system where the item is configured (“client” level or “company” level). Client     validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A isDeleted             Jobprofiles GET jobprofiles The jobProfiles endpoint returns information about the job profiles (Dutch: "Functie informatie") registered.   https://api.youserve.nl/wfm/v1.0/ jobprofiles   Retrieve 1 jobProfile by adding the id of the employee. https://api.youserve.nl/wfm/v1.0/ jobprofiles /<id>    Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/wfm/v1.0/jobprofiles? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   Data mapping Property Description Example HR Core Business shortName Code or short name of the Job Profile SE 97 Functie code fullName Name or full title of the Job Profile Software Engineer 5 97 Functie omschrijving jobTitle Job title description Senior Software Developer 932 Visitekaartje validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A   Leaves Returns a list of all leaves for the tenant specified in the request header consisting of: https://api.youserve.nl/wfm/v1.0/leaves    Retrieve 1 item by adding the id of the leave. https://api.youserve.nl/wfm/v1.0/leaves/<id>     Retrieve all leaves from 1 person: https://api.youserve.nl/wfm/v1.0/leaves? personCode=<personcode>   Retrieve only records which   that have changed within the provided date-time (UTC) range https://api.youserve.nl/wfm/v1.0/leaves? from=2022-01-01T09:00:00.000Z&to=2022-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   Data mapping Note:  When person layer is enabled in HRCore Business, the PersonId is equal to PersonCode.   Property Description Example HR Core Business   id Technical and unique ID of the sickness registration. This unique ID is generated by the core system and can not be changed by a user. 12345678 49 -  leave mutkey   employmentId Technical and unique ID, which is unique within the entity and tenant. The ID is generated by the system and can not be changed by a user. 001 49 - Key of the contract   personCode The Id of a unique person within a tenant. 10056832 10519680 - Persoonscode   leaveRequestDate Represents the date the leave was requested. 2022-04-01 Request date / Datum aanvraag   leaveStartDate Represents the startdate of the leave. 2022-07-01    Starting date / Begindatum   leaveEndDate Represents the enddate of the leave. 2022-07-02     End date / Einddatum   leaveDuration   Number of leavehours.  16 Leave (Units) / Verlof(eenheden)   leaveTypeId Represents the code of a type of leave. All leavetypes can be retrieved in the endpoint leavetypes.   10000100 T ype of leave / Verlofsoort   leaveReason Represents the code of a reason of leave. All leavereasons can be retrieved in the endpoint leavereasons   10000195 Leave reason / Reden verlof   leaveTypeOfSettlement Represents if the leavehours should be deducted from the balance or not 1 = Settle / Verrekenen 2 = Do not settle / Niet verrekenen 1 Type of settlement / Soort verrekening   leaveRequestStatus Represents the status of the leave request: granted, denied, etc 1 = Approved / Goedgekeurd 2 = To be approved / Te fiatteren 3 = Rejected  / Afgewezen 1 Status leave request / Status verlofaanvraag   validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A isDeleted Provide the active/inactive status of the sickness record in the core system. False         LeaveBalances Returns a list of all available leave balances based on leave module in HR Core Business. https://api.youserve.nl/wfm/v1.0/ leavebalances   Leave balance in HR Core Business   Retrieve 1 leave balance by adding the id of the item. https://api.youserve.nl/wfm/v1.0/ leavebalances /<id>    Retrieve leave balance for 1 person: https://api.youserve.nl/wfm/v1.0/ leavebalances ?personid=<personid>   Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/wfm/v1.0/leavebalances? from=2022-10-01T09:00:00.000Z&to=2022-10-02T09:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   Data mapping  Property Description Example HR Core Business (technical number) id Technical and unique ID of the leave balance.   This unique ID is generated by the system and can not be changed by a user. 35148458 n/a personId The Id of a unique person within a tenant. This field refers to the Id in the endpoint Persons. 1000 Unique Person ID (7014) employmentId Technical and unique ID of the employment or contract This field refers to the Id in the endpoint Employments. 35148469 Key of the contract (49) companyCode Reference to company of the employee 500 CompanyCode employeeCode Reference to the employee 1000 EmployeeCode (22) leaveBalanceDetails yearBeginDate: Begin date of the leave entitlement 2022-01-01 n/a (configuration HRCB) yearEndDate: End date of the leave entitlement 2022-12-31 n/a (configuration HRCB) expirationDate: Date of expiration of the entitlement. The leave hours are canceled after this date 2023-07-01 n/a (configuration HRCB) leaveTypeId: This field refers to the shortName  in the endpoint LeaveTypes. 10004750 n/a (configuration HRCB) basicRights: The leave entitlements (in hours) granted per leave type. 160,00 n/a (configuration HRCB) ageRelatedLeaveHours: The leave entitlements (in hours) per leave type based on age and AOW age together. 8,00 n/a (configuration HRCB) yearsOfServiceRelatedHours: The leave entitlements (in hours) per leave type based on years of service. 8,00 n/a (configuration HRCB) additionalIndiviualRights: The extra rights granted (per hour) individually per leave type. 32,00 n/a (configuration HRCB) transferredRights: The transferred entitlements (per hour) per leave type. 8,99 n/a (configuration HRCB) hoursTakenNotSettled: The sum of the booked leave per leave type with status is "Approved" and "not to be settled". Hours are not substracted from the balance. 4,00 n/a (configuration HRCB) hoursTaken: The sum of the booked leave per leave type with status is "Approved".  24,00 n/a (configuration HRCB) balance: Total of leave balance for given leave type.  160,00 n/a (configuration HRCB) validFrom The date from which the record is valid 2020-04-01 Reference date (peildatum) validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record (9999-12-31). 9999-12-31 2020-05-01 n/a isDeleted Provide the active/inactive status of the record in the core system. False n/a       LeaveBalancesPayroll Returns a list of all available leave balances based on payroll calculations for the tenant. https://api.youserve.nl/wfm/v1.0/ leavebalancespayroll   Retrieve 1 LeaveBalancesPayroll by adding the id of the item. https://api.youserve.nl/wfm/v1.0/ leavebalancespayroll /<id>    Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/wfm/v1.0/leavebalancespayroll? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   Data mapping  Property Description Example HR Core Business id Unique ID of the leave entitlements.   This unique ID is generated by the system and can not be changed by a user. 235905542021 7 Combined field of: [EmployeeId] +    [Payroll year]   +  [Payroll period] Example: EmployeeId= 23590554 Payroll Year = 2021 Payroll Period = 7 ID = 23590554202107 personId The Id of a unique person within a tenant. 10056832 7014 - Unique Person ID employeeID Unique technical ID of the employee 23590554 EmployeeId employmentId Technical and unique ID, which is unique within the entity and tenant. The ID is generated by the system and can not be changed by a user. 001 49 - Key of the contract companyCode Reference to company of the employee 001 CompanyCode employeeCode Reference to the employee T0120 EmployeeCode payrollYear Year of the monthly or 4-weekly payroll calculation 2021 PayrollYear payrollPeriod Period of the monthly or 4-weekly payroll calculation  7 PayrollPeriod   leaveBalanceLegalHoliday Leave balance for regular leave as calculated by the payroll 138,40 leaveBalanceLegalHoliday payroll element =  10524591 leaveBalanceAboveLegal Leave balance for regular leave as calculated by the payroll 41,02 leaveBalanceAboveLegal payroll element =  10524590 leaveBalanceTVT Leave balance for "time for time" calculated by the payroll 24,00 LeaveBalanceTVT payroll element = 10524137 leaveBalanceATV Leave balance for "Reduction of working hours" calculated by the payroll 48,00 LeaveBalanceAtv payroll element = 10524136     Leave types The endpoint r eturns a list of all leave types . https://api.youserve.nl/wfm/v1.0/ leavetypes   Data mapping Property Description Example HR Core Business shortName Short name of leave type 123     fullName full name of leave type Leave     level Indicates the level in HRCore Business where the item is configured: system, client, company. company     companyCode   If level is "company" then the         validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A isDeleted Provide the active/inactive status of the record in the core system. False         Leave reasons The endpoint r eturns a list of all leave reasons . https://api.youserve.nl/wfm/v1.0/ leavereasons   Data mapping Property Description Example HR Core Business shortName Short name of leave reason 123     fullName full name of leave reason compassionate leave     level Indicates the level in HRCore Business where the item is configured: system, client, company. company     companyCode   If level is "company" then the         validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A isDeleted Provide the active/inactive status of the record in the core system. False             Locations The endpoint r eturns a list of all locations . https://api.youserve.nl/wfm/v1.0/ locations   The valueList can be configured on different levels in HRCB; system   - The 1st level a property can be defined, this is the highest level. client  - The 2nd level, these items are defined on the tenant level and generally defined by the customer company   - The 3rd level, these items are defined on company level, meaning only relevant for the specific company the properties are defined for The company code is returned as part of the company type   Data mapping Property Description Example HR Core Business shortName Short name of location AMS     fullName full name of location Amsterdam     level Indicates the level in the core system where the item is configured (“client” level or “company” level). Client     validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A isDeleted Provide the active/inactive status of the sickness record in the core system. False         Maternityleaves Returns a list of all maternity leaves for the tenant specified in the request header consisting of: https://api.youserve.nl/wfm/v1.0/ maternity leaves   Retrieve 1 maternity leave by adding the id of the item. https://api.youserve.nl/wfm/v1.0/ maternity leaves/<id>    Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/wfm/v1.0/maternityleaves? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   Data mapping Property Description Example HR Core Business id Technical and unique ID of the   maternity  registration. This unique ID is generated by the core system and can not be changed by a user. 12345678 7593 -  Mutkey of the maternity isDeleted Provide the active/inactive status of the record in the core system. False   personId The Id of a unique person within a tenant. 10056832 7014 - Unique Person ID employmentId Technical and unique ID, which is unique within the entity and tenant. The ID is generated by the system and can not be changed by a user. 001 49 - Key of the contract startDate The first date of the sickness case. 2010-10-01 7594 - Begindatum verlof / WAZO firstWorkingDay The first day the employee appears at his work after the maturity leave period. 2010-10-04 7596 - eerste werkdag     Organization Units The organizationUnits endpoint returns information about the organization structures registered in Youforce, including:  Hierarchical information OrganizationUnit types Management information https://api.youserve.nl/wfm/v1.0/ organizationunits   Retrieve 1 item by adding the id of the item. https://api.youserve.nl/wfm/v1.0/ organizationunits /<id>    Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/wfm/v1.0/organizationunits? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   Data mapping Property Description Example HR Core Business id Unique id of the organization unit 12345678 N/A Mutkey organisatorische eendheid shortName Code or short name of the Organization Unit PD 548 Code organisatorische eenheid fullName Name or full title of the Organization Unit Product Development 549 Naam organisatorische eenheid parentOrgUnit Code of the parent organization unit PD_EU 6000 Bovenliggende organisatorische eenheid organizationUnitType Type of organization unit Divisie 7475 Type organisatorische eenheid manager Unique id of the manager 1234567 N/A Mutkey medewerker managerPersonCode deprecated       managerPersonId The globally unique id assigned to an the management employee 12345678 10519680 Persoon nummer Corresponds with: Endpoint: Person, Property: personCode validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The date from which the record is no longer valid. Will contains a default date in case no “end date“ has been defined for the record. 2020-05-01   9999-12-31 N/A  N/A isDeleted           Organization unit types The endpoint r eturns a list of all  organization unit types: https://api.youserve.nl/wfm/v1.0/organizationunittypes    The valueList can be configured on different levels in HRCB; system   - The 1st level a property can be defined, this is the highest level. client  - The 2nd level, these items are defined on the tenant level and generally defined by the customer company   - The 3rd level, these items are defined on company level, meaning only relevant for the specific company the properties are defined for The company code is returned as part of the company type   Data mapping   Property Description Example HR Core Business HR Core Beaufort Data type shortName Short name of item AMS         string fullName full name of the item Amsterdam         string level Indicates the level in the core system where the item is configured (“client” level or “company” level). Client         string validFrom The date from which the record is valid 2020-04-01 N/A Peildatum N/A N/A YYYY-MM-DD ISO 8601 validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A N/A N/A YYYY-MM-DD ISO 8601 isDeleted                 Persons The endpoint persons gives a list of all persons (HRCore Business : "Medewerker > Persoon") ) of the tenant. https://api.youserve.nl/wfm/v1.0/persons   Retrieve 1 person by adding the id of the employee. https://api.youserve.nl/wfm/v1.0/persons/<id>     Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/wfm/v1.0/persons? from=2022-01-01T09:00:00.000Z&to=2022-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   Data mapping Property Description Example HR Core Business id The globally unique id assigned to an employee 12345678 7014 Uniek Persoonlijk ID (UPI) personCode The unique id assigned to the employee 32789 10519680 Persoon nummer initials The initials of the employee A.B. 25 Voorletters firstNames The official given names of the employee Amy Beatrice 51 Voornamen knownAs The name which is used by the employee as first name Amy 165 Roepnaam lastNameAtBirth The last name at birth of the employee. Also known as the family name Vries 24 Achternaam lastNameAtBirthPrefix The prefix of the employee's last name at birth de 26 Voorvoegsels lastName The last name used by the employee at present de Vries - van Eijck 524 Opgemaakte naam aanhef The value is determined by the setting in nameAssembleOrder lastNamePrefix (not recommended to use this field. This field is the same as lastNameAtBirthPrefix) The prefix of the employee's last name at birth de 26 Voorvoegsels nameAssembleOrder Code of the assemble order used by the core system for the last name. Values: 0 = Partner's name + own last name 1 = Own last name only 2 = Partner's name only 3 = Own last name + partner's name 4 = Compound surname 3 28 Eigennaam code identity Identity field Johnson@email.com 7013 Identity partnerName The last name of the employee's partner Eijck 27 Naam Partner partnerNamePrefix The prefix of the partner's last name Van 166 Voorvoegsels Partner titlePrefix Formal title prefix drs. 94 Titel voor titleSuffix Formal title suffix Msc 95 Titel na gender Gender of the employee 2 36 Geslacht (0) Not known (1) Male (2) Female (9) Not applicable dateOfBirth Date of Birth 1986-02-12 35 geboorte datum deceased This field indicates if an employee is deceased when false the property is not returned true 10302568 Datum overlijden validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A isDeleted Provide the active/inactive status of the record in the core system. False     phoneNumbers List of phone numbers and types Home +3188 123 45 67 7376 Telefoonnummer privé Mobile +316 12 34 56 78 7377 Telefoonnummer mobiel emailAddresses Private email addresses of the employee Private p.user@example.com 7213 E-mailadres privé Addresses List of addresses   type Home street Kerkstraat 391 Straat houseNumber 1 392 Huisnummer houseNumberAddition C 393 Huisnummer toevoeging additionalAddressLine 2nd floor 8099  Locatie omschrijving postalCode 1234 AB 394 Postcode city Amersfoort 395 Woonplaats country NL 34 Woonland   type Postal street Poststraat 7572 Straat (postadres) houseNumber 1 7573 Huisnummer (postadres) houseNumberAddition A 7574 Huisnummer toev (postadres) additionalAddressLine 2nd floor 8100 Locatie omschrijving (postadres) postalCode 1234 AB 7575 Postcode (postadres) city Amersfoort 7576 Plaats (postadres) country NL 7571 Land (postadres)   Sickleaves Returns a list of all sick leaves for the tenant specified in the request header consisting of: https://api.youserve.nl/wfm/v1.0/sickleaves    Retrieve 1 item by adding the id of the sickleave. https://api.youserve.nl/wfm/v1.0/sickleaves/<id>     Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/wfm/v1.0/sickleaves? from=2022-01-01T09:00:00.000Z&to=2022-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   Data mapping Property Description Example HR Core Business id Technical and unique ID of the sickness registration. This unique ID is generated by the core system and can not be changed by a user. 12345678 7471 - Key of the sickness isDeleted Provide the active/inactive status of the sickness record in the core system. False   personId The Id of a unique person within a tenant. 10056832 7014 - Unique Person ID employmentId Technical and unique ID, which is unique within the entity and tenant. The ID is generated by the system and can not be changed by a user. 001 49 - Key of the contract startDate The first date of the sickness case. 2010-10-01 7206 - Eerste verzuimdag expectedRecoveryDate The expected recovery date. 2010-10-04 7443 - Verwachte hersteldatum sicknessType Type of sickness.   1 = Sick 2 = Illness due to pregnancy 3 = Organ donation 5 = Occupational accident 9 = Accident fault by third parties   in Dutch: 1 = Ziek 2 = Ziekte door zwangerschap 3 = Orgaandonatie 5 = Bedrijfsongeval 9 = Ongeval schuld derden 5 7107 - Soort Ziekte recoveryDate The recovery date is defined as the first day the employee appears at his work after a sickness period. 2010-10-05 7207 - Eerste werkdag safetynetCase Reason of Safetynet case   N/A partial recovery startDate illnessPercentage 2010-10-05 80 7464 - Ziektepercentage therapeutic period startDate endDate workingAmount workingPercentage 2010-10-07 2010-10-10 16 40  7089 - Arbeidstherapiepercentage      

Swagger documentation The following swagger pages gives an overview of the endpoint: IAM User endpoint  User endpoint   The user endpoint supports the retrieval of users and gives the ability to set the email address as identity for a user. The next methods are supported as part of the users endpoint. https://api.youserve.nl/iam/v1.0/users GET Allows retrieving a single employee based on employeeId for the tenant specified in the request header. https://api.youserve.nl/iam/v1.0/users(employeeId=12345) Supports the following parameter as part of the resource path: employeeId   - The unique id assigned to an employee. This value is available in the Employees endpoint with the property PersonCode. Returns a   200 OK  when successful PATCH Allows to update or set an email address as identity for a specific user based on employeeId  (PersonCode in Employees endpoint) for the tenant specified in the request header. https://api.youserve.nl/iam/v1.0/users(employeeId=12345)/identity Supports the following parameter as part of its request body: id - email address of the employee which is to be used for SSO { "id": "user@customer.com" } Returns a   204 No content   when successful Visibility of the change in Youforce portal Please note that updating the identity through this endpoint will update the identity in the Youforce authentication system will NOT show the values in Youforce portal Our authentication system is not running on the same service as the portal UI. The synchronization is just one way: Changes done in the authentication system direct will not reflect in the Youforce portal UI Changes done in this UI will reflect in the authentication system Datamapping Parameters Description Example Data type employeeId The unique id assigned to the employee by the HR Core 12345 string id User id of the employee used in the Youforce authentication system HR Core Business: (NL) PING Identiteit (elementnr.  10523564) c7e230db-2a7f-4ef0-ad1d-9d30e7d94a2f string sourceId Username of the user in the Youforce portal.  HR Core Business: (NL) Gebruikersnaam (elementnr. 61) XX123456 string identityId UPN/Identity in the customer authentication system that takes care of authentication HR Core Business: (NL) Identity (elementnr. 7013) user@customer.com string

The File API allows you to download or upload files directly from Youforce, over HTTPS using the tool of your choice.

  Swagger documentation The following swagger page gives an overview of the endpoints: MLM API v1 MLM API v2 Endpoints Companies The entity Companies contains a lot of data related to the existing sub-companies within a tenant/client, such as address details and contact details. https://api.youserve.nl/mlm/companies    Filters Single company - Retrieve specific company by adding the id of the company. GET https://api.youserve.nl/mlm/companies/<id>   Companycode - Retrieve specific company by filtering on companycode. https://api.youserve.nl/mlm/companies?companyCode=<companyCode>   Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request.  By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/companies?ChangedAfter=2022-01-01&ChangedUntil=2022-12-01     Data mapping PI field Description Example HR Core Business (r1) Id Technical and unique Id for a company. The Id is unique within the entity and tenant. The Id is generated by the system and can not be changed by a user. 35146808 mutKey of company code Code of company 500 Company code NL: Bedrijfscode name Name of the company Icommus Company name NL: Bedrijfsnaam totalWorkAmount I ndicates the full-time hours per period within a specific company. For example 40 or 36 hours per week. 40 Hours period NL: Uren periode Element nr: 465 establishmentCountry Country of company NL Country of establishment NL: Vestigingsland bedrijf Element nr: 10525700 address: street Street of company Icommuslaan Street NL: Straat Element nr: 29 address:  houseNumber house number of company 500 House number NL: Huisnummer Element nr: 30 address: houseNumberAddition addition to house number of company a House number addition NL: Huisnummer toevoeging Element nr: 31 address:  postalCode postal code of company 5050 IC Postal code NL: Postcode Element nr: 32 address:  city city of company Amsterdam Municipality NL: Woonplaats Element nr: 33 address: country       mailingAddress: boxnumber  boxnumber of company  6060 P.O. box NL:  Postbus Element nr:  446 mailingAddress: postalCode Post code of boxnumber of company  6060 AB Post code P.O. box address NL:  Postcode postbusadres Element nr: 447 mailingAddress: cityTown city of boxnumber of company Amsterdam Town P.O. box address NL:  Woonplaats postbusadres Element nr: 448 validFrom Start date of the company set 2020-01-01 Referencedate NL:  Peildatum validUntil End date of the company set. Referencedate - 1 of successive version. If no successive version then value is 999-12-31. 9999-12-31  N/A isDeleted Provide the active/inactive status of the record in the core system. false N/A   Contracts The endpoints /employees and /contracts exposes all the corresponding details of a contract belonging to an employee. (HRCB: "Medewerker > Contract"). To retrieve the list of all available contracts within a tenant the Contract endpoint can be used without using any additional parameters. https://api.youserve.nl/mlm/contracts   Filters Single employment - Retrieve specific employment by adding the id of the employment. https://api.youserve.nl/mlm/contracts/<contractid>     PersonId - In case all contracts from a specific person are needed, this can be retrieved based on the “personId” https://api.youserve.nl/mlm/contract?personId=<personId>   Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request.  By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/contracts?ChangedAfter=2020101&ChangedUntil=20200601   Data mapping Fields marked with   (V)   should be connected with the results of the endpoint ‘Valuelists’. API field Description Example HR Core Business (r1) Id Technical and unique Id for a contract. The Id is unique within the entity and tenant. The Id is generated by the system and can not be changed by a user. 23456789 49 - Mutkey of the contract isDeleted Provide the active/inactive status of the Contract in the core system. False   personId The Id of a unique person within a tenant. 10056832 10519680 - personNumber employeeCode Logical code of the employee or employment (reference). 01 22 - Medewerkercode contractCode Code of the contract. 01 91 - Contract Id company Unique (alphanumeric) identifier of the company (legal entity) with which the contract is concluded. 004 18 - Company code originalHireDate The first hire date of original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee. 2010-10-01 308 - Datum indienst organisatie dischargeDate The end date/discharge date of the employment. This is always an ‘up to and including’ date. In unknown the field will not be visible in the API. 2018-12-31 10520479 - Geplande laatste datum indienst hireDate The hire date of the employment. 2017-05-01 39 - Datum indienst employmentType   (V) Type of employment like Internal Employee, Contractor, Wachtgelder shortName: Code or short name of the employment type fullName: name or full title of the employment type CNTR 7393 - Type Medewerker contractType   (V) Type of the contact like indefinite period ('onbepaalde tijd') or given time ('bepaalde tijd'). Bepaalde tijd 10204687 - Contract type jobProfile Official job title or job profile of the employment. The Job profile contains the following details: shortName > Code or short name of the job profile. DEV 97 - Functie organizationUnit Official organization unit of employment. The Organization Unit contains the following details: reference Id to the OrgUnit. ShortName: Code or short name of the organization Unit PD 6000 - Organisatorische eenheid fullTimeWorkingAmount I ndicates the full-time hours per period within a specific company. For example 40 or 36 hours per week.  36 Uren periode (465). NB: confingured on company level.  noRisk indicator of noRisk status false (default) No Risk polis van toepassing endDateNoRisk Last date of noRisk status 2022-12-31 Einddatum no risk periode phoneNumbers type number 088-1004300 Business : 7374 - Telefoonnummer intern emailAddresses type address AnneMarie@work.com Business : 7212 - E-mailadres workingAmount - amountOfWork I ndicates the full-time hours per period for this employment 36 Uren periode (465) workingAmount - unitOfWork (V) Indicator of unit type of amount of work Hours   workingAmount - periodOfWork (V) Indicates the period for which amountOfWork and unitOfWork are defined 1 Dagen/uren per  (463) 1 = "Week" 2 = "FourWeeks" 3 = "Month" 4 = "Quarter"   Employees (Description of Employees endpoint reflects v2.0 of Employees endpoint. Employees v2.0 is the current version of the endpoint) The endpoint   /employees   will return unique persons with their associated contracts. The response body provides a list of active and inactive employee records for a specific tenant, which needs to be specified in the request header. Details we’ll expose are personal details, partner details, contact information, and the latest address details. Also, the corresponding and most relevant contract versions of this Person are included in this endpoint.   To fetch the list of all employees (persons with contracts) within a tenant the Employee endpoint can be used without using any additional parameters. https://api.youserve.nl/mlm/employees    Filters PersonId/ PersonCode - In case specific person incl. contract records are needed, this can be retrieved based on the “personId” or “personCode”. https://api.youserve.nl/mlm/employees/<personId>  https://api.youserve.nl/mlm/employees?personCode=<personCode>    When person layer is enabled in HRCore Business, the PersonId is equal to PersonCode. If so, personId can also be used in filtering: https://api.youserve.nl/mlm/employees?personCode=<personId>    Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request.  https://api.youserve.nl/mlm/employees?ChangedAfter=2020101&ChangedUntil=20200601   Data mapping Data mapping of Employees endpoint can be found in the description of the Persons and Contracts endpoint.   Versions of the endpoint Employees The Employees endpoint has 2 versions available. V1 exposes all versions of the employee (deprecated) V2 exposes only the active versions of the employee Add the versioning to the header of the request using " Accept-version " "2.0": Example requesting v2.0 using postman   For more explanation, read the article about employees versions.         Jobprofiles This endpoint returns all the relevant data regarding the job profiles registered in Youforce, like Job family information & Job profile descriptions. https://api.youserve.nl/mlm/ jobprofiles JobProfiles can be configured on different levels in the core system, on ‘client level’ or on 'company level'. The endpoint will provide details regarding the the level the JobProfile belongs to. In case a JobProfile belongs to a specific subcompany of a client, the response will also show the corresponding “companyCode”. (Dutch: "Functie informatie")   Output example 1 : JobProfile on client (tenant) level { "validFrom": "2011-01-01", "validUntil": "9999-12-31" "extensions": [], "id": "45", "fullName": "Functie 45", "level": "client", "isDeleted": false } Output example 2 : JobProfile on company level { "validFrom": "2014-04-01", "validUntil": "9999-12-31" "extensions": [], "id": "185", "fullName": "Functie 185", "level": "company", "companyCode" : "3511" "isDeleted": false }     Filters Single job profile - Retrieve 1 jobProfile by adding the id of the jobprofile. https://api.youserve.nl/mlm/ jobprofiles /<id>     Level - Filter out specific Job Profiles corresponding to a specific “level”. https://api.youserve.nl/mlm/jobprofiles?level=client   Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request.  By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/ jobprofiles ?ChangedAfter=2020101&ChangedUntil=20200601     Data mapping Fields marked with   (V)   should be connected with the results of the endpoint ‘Valuelists’. API field Description Example HR Core Business (r1) iD     4 fullName The full name of the Job Profile. Developer02 97 - DEVV. FLDDES level Indicates the level in the core system where the job profile is configured (“client” level or “company” level).     companyCode In case the above level is indicated as “company”, the API expose also the corresponding “companyCode”. In case the Job Profile is configured at “client” level, the value of this field is “NULL” and will not be shown in the API response. “50320014” or not shown   isDeleted Provide the active/inactive status of a JobProfile in the core system. False   validFrom Start Date of the Job Profile. 2020-05-22   validUntil End Date of the Job Profile. 9999-12-31     Maternityleaves This endpoint will provide all the needed data regarding Maternity Leave of an employee, like contractID, maturinityID, ReportingDate, startDate & firstWorkingDay. https://api.youserve.nl/mlm/ maternity leaves   Filters Single maternity leave - Retrieve specific maternity leave by adding the id of the leave. https://api.youserve.nl/mlm/ maternity leaves/<id>     PersonId - In case all maternityleaves of a specific person are needed, this can be retrieved based on the “personId” https://api.youserve.nl/mlm/maternityleaves?personId=<personid>     ContractId - In case all maternity leaves of a specific contract are needed, this can be retrieved based on the “contractId” https://api.youserve.nl/mlm/maternityleaves?contractId=<contractid>     Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request.  By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/sickleaves?ChangedAfter=2020101&ChangedUntil=20200601     Data mapping Fields marked with   (V)   should be connected with the results of the endpoint ‘Valuelists’. API field Description Example HR Core Business (r1) Id Technical and unique ID of the maternity leave case. This ID is unique within the entity and tenant. The ID is generated by the system and can not be changed by a user. 4320628 7593 - Key of the maternity isDeleted Provide the active/inactive status of the Maternity case in the core system. False   personId The Id of a unique person within a tenant. 10056832 10519680 - personNumber contractID Technical and unique ID. This ID is unique within the entity and tenant. The ID is generated by the system and can not be changed by a user. 34567 49 - Key of the contract reportingDate The recovery date is defined as the first day the employee appears at his work after a maternity period. (date) 7595 - Datum melding startDate Start date of the maturity leave. (date) 7594 - Begindatum verlof / WAZO actualDeliveryDate The actual date of birth of the child. (date) 7599 - Feitelijke bevallingsdatum firstWorkingDay The first day the employee appears at his work after the maturity leave period. (date) 7596 - Eerste werkdag probableDeliveryDate The probable date of delivery. (date) 7598 - Vermoedelijke bevallingsdatum multipleBirthIndication In case more then one child is expected, this can be defined in both core systems. Value “true” indicates that a Multiple birth is expected for this specific Maternity Leave case. false / true 7350 - Meerling   Organization Units The organization structure describes the organization in terms of business unit, departments, divisions, etc. As well how these are related to each other. Based on the organization structure it's clear ‘how’ units are related, ‘which’ department is responsible for ‘what’. https://api.youserve.nl/mlm/ organizationunits   Filters Single organisation unit - Retrieve specific org unit by adding the id of the org unit. https://api.youserve.nl/mlm/ organizationunits /<id>     Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request.  By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/ organizationunits ?ChangedAfter=2020101&ChangedUntil=20200601    Data mapping Fields marked with   (V)   should be connected with the results of the endpoint ‘Valuelists’. API field Description Example HR Core Business (r1) Id Technical and unique id of the organization Unit. the Id is unique within the entity and tenant. The id is generated by the system and can not be changed by a user. 12009338 6000 - Key org unit shortName Code or short name of the organizational unit. SAL_NL 548 - Code OE fullName Name of the organization unit. Sales Netherlands 549 - Naam OE parentOrgUnit Code of the parent organization unit SALES_EU 6000 - Organisatie eenheid Is the reference to the logical code isDeleted Provide the active/inactive status of the Org Unit in the core system.     organizationUnitType   (V) Code for the organization unit type. BU 7475 - Type organisatie manager Manager of the Organisation Unit. 4005614 7137 - Manager (mutkey of employee) managerPersonId The globally unique id assigned to an the management employee 12345678 10519680 -  Persoon nummer Corresponds with: Endpoint:   Person, Property:   personCode validFrom Start date 2020-01-01   validUntil End date 9999-12-31     Persons The endpoint persons  expose all the available versions of a unique person, so historical, current, and future versions. (HRCore Business : "Medewerker > Persoon") )  To retrieve the list of all active persons within a tenant the Persons endpoint can be used without using any additional parameters. https://api.youserve.nl/mlm/persons   Filters Single person - Retrieve specific person by adding the id of the person. https://api.youserve.nl/mlm/persons/<personid>     Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request.  By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/persons?ChangedAfter=2020101&ChangedUntil=20200601     Data mapping Fields marked with   (V)   should be connected with the results of the endpoint ‘Valuelists’. API field Description Example HR Core Business (r1) id personId The Id of a unique person within a tenant. 10056832 10519680 - personNumber personCode The logical person code of the employee. 4005614 7014 - Uniek Persoonlijk ID (UPI) isDeleted Provide the active/inactive status of the Person in the core system. False   initials The initials of the employee. Format depends. A.M.  25 - Voorletters firstNames The official given names of the employee as stored in the HR Core system. Anne Marie  51 - Voornamen knowAs The name is used by the employee as his first name. Amy  165 - Roepnaam lastNameAtBirth The last name at birth of the employee. Also known as the family name. Vries  24 - Achternaam lastNameAtBirthPrefix The prefix of the last name at birth. de  26 - Voorvoegsel lastName The last which is currently used by the employee as his last name. Vries - Van Eijck  524 - Opgemaakte naam aanhef lastNamePrefix (not recommended to use this field. This field is the same as lastNameAtBirthPrefix) The prefix of the last name at birth. de  26 - Voorvoegsel nameAssembleOrder   (V) Code of the assemble order that the core system uses for the Last Name. The assembly order is depending on the core system and the logic behind it. C  28 - Eigennaam code partnerName The partner's last name. Eijck  27 - Naam Partner partnerNamePrefix The prefix of the partner's last name. van  166 - Voorvoegsel Partner titlePrefix The formal title will be used as a prefix before the name like Doctor, Professor, etcetera. Bachelor 94 - Titel voor Description titleSuffix The formal title which will be used as postfix after the name like MSc or Master of Science. MsC 95 - Titel na Description gender   (V) Gender of the person conform the ISO/IEC 5128 standard (0) Not known (1) Male (2) Female (9) Not applicable 2 P00330 - Geslacht M = Man / Male V = Vrouw / Female birthDate Date of Birth. 1978-05-25 35 - geboorte datum deceasedDate Indicated if the employee is deceased. (if True > date format) 10302568 - Datum overlijden nationalIdentificationNumber Country specific Identification number. 1744263858 10000018 - Burgerservice nummer userUID The Digital Identity of the user from the portal, to be used for SSO. a061c395-558f-49c7-991c-633aa9afa529 10523564 - PING ID address type streetName houseNumber houseNumberAddition postalCode city country 01 Kerkstraat 26 A 3567 AH Hilversum Nederland 01 Living address / 02 Postal address 391 - straat 392 - Huisnummer 393 - Huisnummer toevoeging 394 - Postcode 395 - Woonplaats 34 - Woonland > description phoneNumbers type number 0546-453212 Home : 7376 - Telefoonnummer prive Mobile : 7377 - Telefoonnummer mobiel emailAddresses type address AnneMarie@privatemail.com Prive: 7213 - E-mailadres Prive   Role Assignments The Role assignments endpoint delivers the role an employee has in the organization.  https://api.youserve.nl/mlm/roleassignments   Filters Single roleassignment - Retrieve 1 role assignments by adding the id of the item. https://api.youserve.nl/mlm/roleassignments/<id>   OrganizationUnitId - Retrieve all roleassignments for 1 specific organizational unit: https://api.youserve.nl/mlm/roleassignments?organizationUnitId=<organizationUnitId>   Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request.  By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/ roleassignments ?ChangedAfter=2020101&ChangedUntil=20200601   Data mapping Fields marked with   (V)   should be connected with the results of the endpoint ‘Valuelists’. API field Description Example HR Core Business (r1) Id The id of the role Code or the role assignment 658332 960 - Key of the role assignment organizationUnitId The Id of the Organization Unit where this Role Assignment belongs to. 12345 548 - Code of the Organisation Unit Key of the Organisation Unit. Referring to:  organizationunits.id shortName The shortname of the role  DM1 549 - (short)name of the role assignment fullName The fullname of the role      personId The Id of a unique person within a tenant. 10056832 10519680 - personNumber Referring to: Persons.id includingChildOrgUnits Refers to the level of authorisation of a specific role within an organisation. true / false 913 - includeChildOU validFrom Start date of the role assignment 2020-01-01   validUntil End date of the role assignment 9999-12-31   startDate Start date of the role assignment 2020-01-01   endDate End date of the role assignment 9999-12-31   isDeleted Provide the active/inactive status of the record in the core system. false N/A   Sickleaves Returns a list of all sick leaves for the tenant specified in the request header consisting of: https://api.raet.com/mlm/sickleaves      Filters Single sickleave - Retrieve specific sick leave by searching on id of the sick leave https://api.youserve.nl/mlm/sickleaves/<id>     PersonId - In case all sickleaves of a specific person are needed, this can be retrieved based on the “personId” https://api.youserve.nl/mlm/sickleaves?personId=<personid>     ContractId - In case all sickleaves of a specific contract are needed, this can be retrieved based on the “contractId” https://api.youserve.nl/mlm/sickleaves?ContractId=<contractid>     Active - to retrieve only active sickleaves, use the active parameter https://api.youserve.nl/mlm/sickleaves?active=true   Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request.  By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/sickleaves?ChangedAfter=2020101&ChangedUntil=20200601   Important notes : An important note regarding sickness cases which are fully recovered: in some cases it might happen that the API output of recovered sickness doesn’t expose a “0%” value. This is caused by the fact that sickness data can be created & managed in several different applications (BO4, HRCB, Self Service and external systems). Based on this a MLM-system should only use the “recoveryDate” to verify if a sickness is ‘open’ or 'closed’. All the available sickness versions will exposed as separate data records. The MLM API will expose this data as it’s received it from the core system without additional logic to merge it to one case. All the necessary technical logic to merge these records into one ‘sickness dossier’ according to the 28-days regulation has to be added at the ‘API consumer side’. Data mapping Fields marked with   (V)   should be connected with the results of the endpoint ‘Valuelists’. API field Description Example HR Core Business (r1) Id Technical and unique ID of the sickness registration. This unique ID is generated by the core system and can not be changed by a user. 12345678 7471 - Key of the sickness IsDeleted Provide the active/inactive status of the sickness record in the core system. False   personId The Id of a unique person within a tenant. 10056832 10519680 - personNumber contractId Technical and unique ID, which is unique within the entity and tenant. The ID is generated by the system and can not be changed by a user. 001 49 - Key of the contract reportingDate Date the sickness reported by the employer. 2010-10-01 7189 - Datum ziekmelding startDate The first date of the sickness case. 2010-10-01 7206 - Eerste verzuimdag hoursWorkedFirstDay Hours worked on the first sickness date. This could be relevant if the employee gets sick during his working day. 2,00 7423 - Gewerkte uren eerste verzuimdag expectedRecoveryDate The expected recovery date. 2010-10-04 7443 - Verwachte hersteldatum sicknessType   (V) Type of sickness.   1 = Sick 2 = Illness due to pregnancy 3 = Organ donation 5 = Occupational accident 9 = Accident fault by third parties   in Dutch: 1 = Ziek 2 = Ziekte door zwangerschap 3 = Orgaandonatie 5 = Bedrijfsongeval 9 = Ongeval schuld derden 5 7107 - Soort Ziekte absenceReason Reason for absence. (string) #N/A recoveryDate The recovery date is defined as the first day the employee appears at his work after a sickness period. 2010-10-05 7207 - Eerste werkdag recourse Indicates the right of recourse when the sickness is the result of an accident caused by someone else. (boolean) 7391 - Regres ongoingSickness Indicates if the sickness case is an ongoing sickness case. This means that in the MLM system will tread as part of the previous sickness of the employee. Mostly this is the case if the previous sickness was within 28 days. (boolean) 7075 - Doorlopend ziektegeval safetynetCase Reason of Safetynet case   #N/A date WVP Date of the first sickness of a series of sickness cases. In the Netherlands named ‘the 28 days rule’.   7076 - Date WVP urgentCheckRequired Indicates if an urgent check by the occupational health service is required. (boolean) 7401 - Spoedcontrole expectedFinalResult The expected final result based on the first impression by the manager. For instance, if the manager expects that the employee can fully recover without any restriction for his current Job he can set his expectation so the occupation health service can act on it. (string) 7444 - Verwacht resultaat finalResult   (V) The final result after the employee is recovered. For instance, if the employee returns but in another job. (string) 7470 - Eindresultaat  partial recovery startDate illnessPercentage 2010-10-05 80 7464 - Ziektepercentage  therapeutic period startDate endDate workingAmount workingPercentage  2010-10-07 2010-10-10 16 40  7089 - Arbeidstherapiepercentage  nursing address startDate endDate nameCareAddress streetName number numberAdditional locationDesignation postalCode city region country emailAddress phoneNumber faxNumber 2010-10-04 2010-10-05 Ziekenhuis Rijnstate Wagnerlaan 55 6815 AD Arnhem Gelderland Nederland info@ziekenhuis.nl 088 - 005 8888 7442 - Naam verpleegadres 391 - Straat 392 - Huisnummer 393 - Huisnummer toevoeging 8099 - Locatie omschrijving 394 - Postcode 395 - Woonplaats 10205283 - Regionaam buitenland 34 - Woonland 7447 - E-mailadres 7455 - Telefoon 7375 - faxnummer   Value lists This endpoint returns all the corresponding code & descriptions of pairs of fields that are available in the Medical Leave API.   This reference lists endpoint supports filtering based on type. For example, the property “Gender” will be returned as a value 1 or 2, and based on the value list data the user is able to define that 1 = male & 2 = female. Other examples : “finalResult”; “contractType”; “country”; “employmentType”; “gender”; “nameAssembleOrder”; “organisationUnitType”; “sicknessType” & “workingUnit”.    In ‘Data Mapping’, the fields, which are marked with (V), these fields should be connected with the results of the endpoint ‘Valuelists’. Valuelists can be configured on different levels in the core system, on ‘client level’ or on ‘company level'. On top is these levels there are also 'system level’ Valuelists.   Output example 1 : Valuelists on (core) system level { "validFrom": "2011-01-01", "validUntil": "9999-12-31" "shortName": "1", "fullName": "Man", "type": "gender", "level": "System", "isDeleted": false, }, Output example 2 : Valuelists on client (tenant) level { "validFrom": "2018-08-10", "validUntil": "9999-12-31" "shortName": "2", "fullName": "Stagiair", "type": "employmentType", "level": "Client", "isDeleted": false, },   Retrieve all valuelists: https://api.youserve.nl/mlm/valuelists    Filters Single type - Retrieve details of a specific type of valuelist, based on the “type”. https://api.youserve.nl/mlm/valuelists/<type> example https://api.youserve.nl/mlm/valuelists/employmentType   Level - Filter out specific valuelists corresponding to a specific “level”. https://api.youserve.nl/mlm/valuelists?level=company    Combination level, type - combining the 2 above filters. https://api.raet.com/mlm/valuelists/function?level=company       

This API is intended for Work Force Management systems and allows them to get the data needed for Workforce management systems who are responsible the planning of employees of an organization: Retrieve employee data from Youforce Retrieve organizational structures from Youforce Retrieve job profile information from Youforce

  Swagger documentation The following swagger page gives an overview of the endpoints: IAM API Endpoints Companies GET companies The endpoint GET companies gives a list of company versions of the tenant. GET https://api.youserve.nl/iam/v1.0/companies   Retrieve 1 company by adding the id of the company: GET https://api.youserve.nl/iam/v1.0/companies/<id>   Retrieve only records which that have changed within the provided date-time (UTC) range: GET https://api.youserve.nl/iam/v1.0/companies?from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z. Format:  YYYY-MM-DDTHH:MM:SS.sssZ Data mapping Property Description Example HR Core Business id identifier of the company     mutkey shortName short name of the company     company code fullName full name of the company     company name validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A   Employees GET employees The endpoint GET employees gives a list of employees with the personal and employment details of an employee. GET https://api.youserve.nl/iam/v1.0/employees    The employee endpoint supports the following query string parameters Parameter Description   <id> Retrieve 1 employee by adding the id of the employee. https://api.youserve.nl/iam/v1.0/employees/<id>    personCode Returns a list of employee records filtered by   personId https://api.youserve.nl/iam/v1.0/employees  ?personCode=191166   personId Returns a list of employee records filtered by   personId https://api.youserve.nl/iam/v1.0/employees  ?personId=191166   company Returns a list of all employee records filtered by   company https://api.youserve.nl/iam/v1.0/employees?company=1010A    organizationUnit Returns a list of all employee records filtered by organizationUnit  id https://api.youserve.nl/iam/v1.0/employees?organizationUnit=13612345    from  and  to Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/iam/v1.0/employees? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   isActive Allows to filter out inactive records, returns all records that have been “deactivated“ either due to: validFrom is more than 90 days in the past Deletion of the record (employee) in the core application itself dischargeDate is more than 90 days in the past https://api.youserve.nl/iam/v1.0/employees ? isActive=false   validFrom   Returns a list of employee records filtered based on the   validFrom   and   validUntil Date timestamp format is always according to ISO 8601   YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/employees? validFrom=2020-11-07   validUntil Returns a list of employee records filtered based on the   validUntil Date timestamp format is always according to ISO 8601   YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/employees ? validUntil=2020-11-09     Data mapping Property Description Example HR Core Business id The globally unique id assigned to an employee 12345678 N/A Mutkey medewerker personCode The unique id assigned to the employee 32789 7014 Uniek Persoonlijk ID (UPI)* personId The globally unique id assigned to an employee 12345678 10519680 Persoon nummer initials The initials of the employee A.B. 25 Voorletters firstNames The official given names of the employee Amy Beatrice 51 Voornamen knownAs The name which is used by the employee as first name Amy 165 Roepnaam lastNameAtBirth The last name at birth of the employee. Also known as the family name Vries 24 Achternaam lastNameAtBirthPrefix The prefix of the employee's last name at birth de 26 Voorvoegsels lastName The last name used by the employee at present de Vries - van Eijck 524 Opgemaakte naam aanhef The value is determined by the setting in nameAssembleOrder lastNamePrefix (not recommended to use this field. This field is the same as lastNameAtBirthPrefix) The prefix of the employee's last name at birth de 26 Voorvoegsels nameAssembleOrder Code of the assemble order used by the core system for the last name. Values: 0 = Partner's name + own last name 1 = Own last name only 2 = Partner's name only 3 = Own last name + partner's name 4 = Compound surname 3 28 Eigennaam code partnerName The last name of the employee's partner Eijck 27 Naam Partner partnerNamePrefix The prefix of the partner's last name Van 166 Voorvoegsels Partner titlePrefix Formal title prefix drs. 94 Titel voor titleSuffix Formal title suffix Msc 95 Titel na gender Gender of the employee Female 36 Geslacht   dateOfBirth Date of birth 1986-12-02 N/A N/A deceased This field indicates if an employee is deceased when false the property is not returned true 10302568 Datum overlijden validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A phoneNumbers List of phone numbers and types Home +3188 123 45 67 7376 Telefoonnummer privé Business +3188 345 67 89 7374 Telefoonnummer intern Mobile +316 12 34 56 78 7377 Telefoonnummer mobiel emailAddresses List of email addresses of the employee Business b.user@example.com  7212 E-mailadres Private p.user@example.com  7213 E-mailadres privé Addresses List of addresses   type Home street Kerkstraat 391 Straat houseNumber 1 392 Huisnummer houseNumberAddition C 393 Huisnummer toevoeging additionalAddressLine 2nd floor 8099  Locatie omschrijving postalCode 1234 AB 394 Postcode city Amersfoort 395 Woonplaats country NL 34 Woonland   type Postal street Poststraat 7572 Straat (postadres) houseNumber 1 7573 Huisnummer (postadres) houseNumberAddition A 7574 Huisnummer toev (postadres) additionalAddressLine 2nd floor 8100 Locatie omschrijving (postadres) postalCode 1234 AB 7575 Postcode (postadres) city Amersfoort 7576 Plaats (postadres) country NL 7571 Land (postadres) Employments employeeCode The code of the employee or employment 12345 22 Medewerker code contractId Unique Id for the contract and/or employment 654789 49 Contract mutkey contractCode Code of the contract 1 91 Contract id originalHireDate The first hire date or original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee 2010-10-01 308 Datum in dienst organisatie dischargeDate The end date or discharge date of the employee. This is always an "up to and including" date. In case of no values the field will not be returned as part of the response body 2018-12-31 10520479 Geplande laatste datum indienst note: calculated field: [Geplande laatste datum indienst] = [Datum uitdienst] - 1 day   Datum uitdienst = fieldnr 40 hireDate Date of hire for the employment 2017-05-01 39 Datum indienst endDate Enddate of contract 2022-12-31 7226 Afloopdatum company Unique identifier of company the where contract is concluded 001 18 Bedrijfscode location The location at which the employment is being fulfilled AMF 75 Vestiging site The location at which the employment is being fulfilled Vestiging 1 7449 Werklocatie costCenter The cost center under which the employment is registered 012 53 Kostenplaats classification Cost allocation of the employment 123 474 Classifiecatiekenmerk 1 employmentType Code of the employment type 4 7393 Type medewerker workingAmount Working amount of the employment. amountOfWork: numeric value representing the work amount 40   465 Uren periode periodOfwork: indicates the period for which amountOfWork and unitOfWork are defined Day Week Month Quarter 463 Dagen/uren per Week Maand jobProfile The job profile code 9909 DEV 97 Functie organizationUnit The organization unit id 1234567 ZKH 6000 Mutkey organisatorische eenheid   Employments GET employments The employee endpoint returns information about the employments registered in HRCB. GET https://api.youserve.nl/iam/v1.0/employments   The employees endpoint supports the following query string parameters Parameter Description   <id> Retrieve 1 employment by adding the id of the employee. https://api.youserve.nl/iam/v1.0/employments/<id>    personCode Returns a list of employments  records filtered by   personId https://api.youserve.nl/iam/v1.0/employments ?personCode=191166   personId Returns a list of employments  records filtered by   personId https://api.youserve.nl/iam/v1.0/employments ?personId=191166   company Returns a list of all employments  records filtered by   company https://api.youserve.nl/iam/v1.0/employments?company=1010A    organizationUnit Returns a list of all employments  records filtered by organizationUnit  id https://api.youserve.nl/iam/v1.0/employments?organizationUnit=13612345    from  and  to Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/iam/v1.0/employments? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   isActive Allows to filter out inactive records, returns all records that have been “deactivated“ either due to: validFrom is more than 90 days in the past Deletion of the record (employee) in the core application itself dischargeDate is more than 90 days in the past https://api.youserve.nl/iam/v1.0/employments? isActive=false   validFrom Returns a list of employments  records filtered based on the   validFrom   and   validUntil Date timestamp format is always according to ISO 8601   YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/employments? validFrom=2020-11-07   validUntil Returns a list of employments  records filtered based on the   validUntil Date timestamp format is always according to ISO 8601   YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/employments? validUntil=2020-11-09     Data mapping Property Description Example HR Core Business id Employment id 12459897 49 Contract mutkey personCode The unique id assigned to the employee 32789 7014 Uniek Persoonlijk ID (UPI)* personId The globally unique id assigned to an employee 12345678 10519680 Persoon nummer * employeeCode The code of the employee or employment 12345 22 Medewerker code contractCode Code of the contract 1 91 Contract id validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A originalHireDate The first hire date or original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee 2010-10-01 308 Datum in dienst organisatie dischargeDate The end date or discharge date of the employee. This is always an "up to and including" date. In case of no values the field will not be returned as part of the response body 2018-12-31 10520479 Geplande laatste datum indienst note: calculated field: [Geplande laatste datum indienst] = [Datum uitdienst] - 1 day   Datum uitdienst = fieldnr 40 enddate Enddate of contract 2022-12-31 7226 Afloopdatum hireDate Date of hire for the employment 2017-05-01 39 Datum in dienst company Unique identifier of company the where contract is concluded 001 18 Bedrijfscode location The location of where the employment is being performed 789 75 Vestiging site The location at which the employment is being fulfilled Vestiging 1 7449 Werklocatie costCenter The cost center under which the employment is registered 012 53 Kostenplaats classification Cost allocation of the employment 123 474 Classifiecatiekenmerk 1 employmentType Code of the employment type 4 7393 Type medewerker jobProfile The job profile code 9909 DEV 97 Functie organizationUnit The organization unit id 1234567 ZKH 6000 Mutkey organisatorische eenheid emailAddresses List of email addresses   Business b.user@example.com 7212 E-mailadres phoneNumbers List of phone numbers and types Business +3188 345 67 89 7374 Telefoonnummer intern workingAmount Working amount of the employment. amountOfWork: numeric value representing the work amount 40   465 Uren periode periodOfwork: indicates the period for which amountOfWork and unitOfWork are defined Day Week Month Quarter 463 Dagen/uren per Week Maand   Jobprofiles GET jobprofiles The jobProfiles endpoint returns information about the job profiles (Dutch: "Functie informatie") registered. GET https://api.youserve.nl/iam/v1.0/ jobprofiles   The endpoint supports the following query string parameters Parameter Description   <id> (Deprecated May 2021) Retrieve 1 jobprofile by adding the id of the employee. https://api.youserve.nl/iam/v1.0/ jobProfiles /<id>    shortName Returns a list of all jobprofile records filtered by shortName https://api.youserve.nl/iam/v1.0/ jobprofiles ?personCode=191166   companyCode Returns a list of valueList records based on companyCode https://api.youserve.nl/iam/v1.0/ jobprofiles ?personId=191166   from  and  to Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/iam/v1.0/jobprofiles? from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   isActive Allows to filter out inactive records, returns all records that have been “deactivated“ either due to: validFrom is more than 90 days in the past Deletion of the record (employee) in the core application itself dischargeDate is more than 90 days in the past https://api.youserve.nl/iam/v1.0/jobprofiles? isActive=false   validFrom Returns a list of jobprofiles  records filtered based on the   validFrom   and   validUntil Date timestamp format is always according to ISO 8601   YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/jobprofiles? validFrom=2020-11-07   validUntil Returns a list of jobprofiles records filtered based on the   validUntil Date timestamp format is always according to ISO 8601   YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/jobprofiles? validUntil=2020-11-09       Data mapping Property Description Example HR Core Business shortName Code or short name of the Job Profile SE 97 Functie code fullName Name or full title of the Job Profile Software Engineer 5 97 Functie omschrijving jobTitle Job title description Senior Software Developer 932 Visitekaartje validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A   Organization Units GET organization units The endpoint organizationUnits gives a list of organizationUnits versions of the tenant. GET https://api.youserve.nl/iam/v1.0/organizationunits   The endpoint supports the following query string parameters Parameter Description   <id> Retrieve 1 organization unit by adding the id of the employee. https://api.youserve.nl/iam/v1.0/organizationunits/<id>    shortName Returns a list of all organizationUnits records filtered by shortName https://api.youserve.nl/iam/v1.0/organizationunits ?personCode=191166   from  and  to Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/iam/v1.0/organizationunits? from=2022-01-01T09:00:00.000Z&to=2022-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   isActive Allows to filter out inactive records, returns all records that have been “deactivated“ either due to: validFrom is more than 90 days in the past Deletion of the record (employee) in the core application itself dischargeDate is more than 90 days in the past https://api.youserve.nl/iam/v1.0/organizationunits? isActive=false   validFrom Returns a list of organizationunits  records filtered based on the   validFrom   and   validUntil Date timestamp format is always according to ISO 8601   YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/organizationunits? validFrom=2022-11-07   validUntil Returns a list of organizationunits records filtered based on the   validUntil Date timestamp format is always according to ISO 8601   YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/organizationunits? validUntil=2022-11-09     Data mapping Property Description Example HR Core Business id Unique id of the organization unit 12345678 N/A Mutkey organisatorische eendheid shortName Code or short name of the Organization Unit PD 548 Code organisatorische eenheid fullName Name or full title of the Organization Unit Product Development 549 Naam organisatorische eenheid parentOrgUnit Code of the parent organization unit PD_EU 6000 Bovenliggende organisatorische eenheid organizationUnitType Type of organization unit Divisie 7475 Type organisatorische eenheid manager Unique id of the manager 1234567 N/A Mutkey medewerker managerPersonId The globally unique id assigned to an the management employee 12345678 10519680 Persoon nummer * validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The date from which the record is no longer valid. Will contains a default date in case no “end date“ has been defined for the record. 2020-05-01   9999-12-31 N/A  N/A   Persons In order to work with the Persons endpoint, the Person layer needs to be enabled in HR Core Business.  GET Persons The endpoint persons gives a list of all persons (HRCore Business : "Medewerker > Persoon") ) of the tenant. GET https://api.youserve.nl/iam/v1.0/persons   The endpoint supports the following query string parameters Parameter Description   <id> Retrieve 1 person by adding the id of the employee. https://api.youserve.nl/iam/v1.0/persons/<id>    from  and  to Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/iam/v1.0/persons? from=2022-01-01T09:00:00.000Z&to=2022-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   isActive Allows to filter out inactive records, returns all records that have been “deactivated“ either due to: validFrom is more than 90 days in the past Deletion of the record (employee) in the core application itself dischargeDate is more than 90 days in the past https://api.youserve.nl/iam/v1.0/persons? isActive=false   validFrom Returns a list of persons  records filtered based on the   validFrom   and   validUntil Date timestamp format is always according to ISO 8601   YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/persons? validFrom=2022-11-07   validUntil Returns a list of persons records filtered based on the   validUntil Date timestamp format is always according to ISO 8601   YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/persons? validUntil=2022-11-09     Data mapping Property Description Example HR Core Business id The globally unique id assigned to an employee 12345678 10519680 Persoon nummer personCode The unique id assigned to the employee 32789 7014 Uniek Persoonlijk ID (UPI)* initials The initials of the employee A.B. 25 Voorletters firstNames The official given names of the employee Amy Beatrice 51 Voornamen knownAs The name which is used by the employee as first name Amy 165 Roepnaam lastNameAtBirth The last name at birth of the employee. Also known as the family name Vries 24 Achternaam lastNameAtBirthPrefix The prefix of the employee's last name at birth de 26 Voorvoegsels lastName The last name used by the employee at present de Vries - Van Eijck 524 Opgemaakte naam aanhef The value is determined by the setting in nameAssembleOrder lastNamePrefix (not recommended to use this field. This field is the same as lastNameAtBirthPrefix) The prefix of the employee's last name at birth de 26 Voorvoegsels nameAssembleOrder Code of the assemble order used by the core system for the last name. Values: 0 = Partner's name + own last name 1 = Own last name only 2 = Partner's name only 3 = Own last name + partner's name 4 = Compound surname 3 28 Eigennaam code partnerName The last name of the employee's partner Eijck 27 Naam Partner partnerNamePrefix The prefix of the partner's last name Van 166 Voorvoegsels Partner titlePrefix Formal title prefix drs. 94 Titel voor titleSuffix Formal title suffix Msc 95 Titel na gender Gender of the employee Female 36 Geslacht   dateOfBirth Date of Birth 1986-02-12 N/A N/A deceased This field indicates if an employee is deceased when false the property is not returned true 10302568 Datum overlijden validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A phoneNumbers List of phone numbers and types Home +3188 123 45 67 7376 Telefoonnummer privé Mobile +316 12 34 56 78 7377 Telefoonnummer mobiel emailAddresses List of email addresses of the employee Private p.user@example.com 7213 E-mailadres privé Addresses List of addresses   type Home street Kerkstraat 391 Straat houseNumber 1 392 Huisnummer houseNumberAddition C 393 Huisnummer toevoeging additionalAddressLine 2nd floor 8099  Locatie omschrijving postalCode 1234 AB 394 Postcode city Amersfoort 395 Woonplaats country NL 34 Woonland   type Postal street Poststraat 7572 Straat (postadres) houseNumber 1 7573 Huisnummer (postadres) houseNumberAddition A 7574 Huisnummer toev (postadres) additionalAddressLine 2nd floor 8100 Locatie omschrijving (postadres) postalCode 1234 AB 7575 Postcode (postadres) city Amersfoort 7576 Plaats (postadres) country NL 7571 Land (postadres)   Valuelists GET valuelists The valueList endpoint returns the descriptions to the codes returned in the IAM entity endpoints. The valueList can be configured on different levels; system   - The 1st level a valueList property can be defined, this is the highest level on which the valueList can be defined and concerns general properties such as “country” client  - The 2nd level, these valueList items are defined on the tenant level and generally defined by the customer company   - The 3rd level, these valueList items are defined on company level, meaning only relevant for the specific company the properties are defined for The company code is returned as part of the company type GET https://api.youserve.nl/iam/v1.0/valuelist  retrieves all valuelist items   GET https://api.youserve.nl/iam/v1.0/valuelist?type=[valulist type]  retrieves only the valuelists of a specific type. Example: retrieve all locations:  https://api.youserve.nl/iam/v1.0/valueList?type=location   In table below, the types are shown, along with the endpoint where they are referenced. IAM property Valuelist type Persons nameAssembleOrder nameAssembleOrder gender gender Employees nameAssembleOrder nameAssembleOrder employmentType   gender gender country country costCenter costCenter classification classification location location Employments endpoint costCenter costCenter classification classification employmentType employmentType location location OrganizationUnits endpoint organizationUnitType organisationUnitType   The endpoint supports the following query string parameters Parameter Description <type> Retrieve only 1 valuelist type,  for instance retrieve all countries: https://api.youserve.nl/iam/v1.0/valueList/country level Returns a list of valuelist records based on the  level. https://api.youserve.nl/iam/v1.0/valuelist?level=client  companyCode Returns a list of valuelist records based on  companyCode https://api.youserve.nl/iam/v1.0/valuelist?companyCode=2  validFrom Returns a list of valuelist  records filtered based on the   validFrom   and   validUntil Date timestamp format is always according to ISO 8601   YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/valuelist? validFrom=2022-11-07 validUntil Returns a list of valuelist records filtered based on the   validUntil Date timestamp format is always according to ISO 8601   YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/valuelist? validUntil=2022-11-09   User The User endpoint is described in a separate article: IAM User endpoint.        

  MLM API The available API’s of Visma | YouServe are developed corresponding with the data which is required for a specific HR domain. This MLM API has an ‘outside in’ set up, which means that each domain contains only the data and endpoints they need. The API’s support all common and domain-specific fields. For instance, the social security number is only available in domains with a legitimate reason, like Medical Leave Management. In other domains, other fields could be available. By using customer-specific ‘extensions’ it’s possible to add extra fields for an API user. This Medical Leave API will expose the necessary data which is needed to do your   sickness case management   according to the Dutch law ‘Wet Poortwachter’. Currently, we support the data entities People, Organisation Units, Sickness registrations, Value lists, Maternity Leaves, RoleAssignments, JobProfiles & Companies by exposing these via different endpoints.    Handle full loads & changes By calling the API the user will by default retrieve the tenant-specific data in full loads. In cases the user prefers to fetch only the changed data, we provide the possibility to use the parameters ‘ChangedAfter' & ‘ChangedUntil’ (see example).     Example date-time format : changedAfter - 2020-08-21T00:00:00.000Z changedUntil - 2020-08-21T12:01:46.077Z   Pagination of the result set To reduce the load of an endpoint each endpoint supports paging. In case the results of an endpoint contain more than 500 records, the results set will end with a ‘nextLink tag’. The nextLink indicates that there are more pages to load. If there is no nextLink at the end of the page, this means that it’s the last page of the result set. Handle deletions The existing endpoints will provide the API consumers a status field that says something about the (in)active status of a specific record. For example in situations where sickness cases were deleted in the core system. The response bodies of the endpoints will have the following flag : "iD" : "123456" "IsDeleted":"false" The active value will be stated as “False” and an inactive (deleted) record will be stated as “True”. All the remaining fields in the deleted records will be empty and not visible in the output anymore. Historical, current & future data The different endpoints in the MLM API provide the most accurate data corresponding with the different data entities (Employee; Employments, Sickness cases,   etcetera.). By executing full loads (and changed) the API exposes default data until 4 years back in history (from today’s date). Besides historical data also future changes will be exposed via the API. All these different data sets will show in ‘versions' by using a ‘ValidFrom’ and a “ValidUntil’ date. These ‘ValidFrom’ and ‘ValidUntil’ are functional dates which are sent to the API by the Visma core systems along with the corresponding data. These dates indicate the duration for which this version of the entity is valid. This makes it possible to expose for example contract details of an Employee multiple years back in time and also the future changes. In case a future change is added to the core system (from 24 hours p/w to 32 hours p/w per 01-01-2021) the API exposes all these versions in ‘time slices’. EXAMPLE OF RECORDS VERSIONS In the example below, the employee changes his working hours on 01-11-2018 into 32 hours. After this change, the system creates a new version of the record with a validFrom and validUntil. On 01-04-2019 he becomes UX designer in the UX team, so the next version is created. Response times API Visma Verzuim (a.k.a. DWC) is a Visma | YouServe partner that integrates with Youforce for employee, organization and sickness data. The data is made available to Visma Verzuim using the Youforce API for Medical Leave Systems (In short: ‘MLM API’).  The Youforce APIs are optimized for availability and scalability: the data is being ‘pre-processed’ for the API consumer. In this way we ensure that data is always available to integrated systems.  Pre-processing means the data is stored in a read optimized database to which the API is connected. The pre-processing also takes data authorization into account. In this way the API and HR Core system remain responsive when dealing with peak loads from consuming systems.  As a consequence it takes time before transactions in Youforce are available to other systems. This is known as ‘stale data’. The delay is normally within 10 to 30 minutes. Structural delays of more than 30 minutes are considered an issue.  Versioning of the different endpoints Some endpoints of the Medical Leave API might offer you multiple versions. Currently, the /employees endpoint has two functional versions. The technical usage of the different versions will be explained below. SWAGGER :   In the Swagger tool this can be executed by switching the version in the right top bar 'Select a definition’ (see example).     After selecting the right version (f.e. V2), the corresponding version will show up in the Swagger documentation.     POSTMAN:   In the Postman tool versioning can be managed by changing the Key 'Accept-Version' to   2.0   (see example). Entity model The MLM domain model contains the following entities     Endpoint Entity Description Employee endpoint Person A natural person. In HR it is more common to talk about employees, but the entity Person is broader than the entity employee. The entity could also contain Persons without any employment with the employer, like contact persons, suppliers, etc. Employee An employee is a person who had, has, or will have employment with the employer.  In natural language, we talk about employees, old employees or former employees.  Employment An Employment or Employment relationship defines the official relation between the employee and the employer. The employment can be based on multiple contracts as long it describes one continuous period of which the employee was employed to the same employer. Sickleave endpoint Sickness leave A sickness leave describes an uninterrupted period of absence because of sickness. Within this period an Employee can be partially recovered, but the sick leave will ends when the Employee is fully recovered. Maternity Leaves endpoint Maternity leave The maternity leave period that the employee is absent because of maternity leave. Sickness related to the pregnancy before or after the Maternity leave is not part of the Maternity leave itself but are separate sickness leave. Company endpoint Company The (legal) company as know by the core system Note: not all Core systems support the legal company, but only the Payroll company. There could be some payroll reasons to split a legal company into 2 different Payroll companies. For instance, if the legal company supports more than one payroll period (e.g. Month + 4 weeks). In that case, the official legal company does not exist. OrgUnits endpoint Organizational Unit The organization structure describes the organization in terms of Business unit, department, teams, etc. and how there are related to each other. Based on the organization structure it's clear how the organization is structured and "which" department is responsible for "what" RoleAssignments endpoint Role Assignment The role assignment describes "who" is responsible for "which role"  for "which period" for the organization unit. For instance "who is the manager" or "who is the financial controller", etc. JobProfiles endpoint JobProfiles All job profiles of the organization.    User The user account of a single employee   Based on the HR domain model we’ve defined the following endpoints : Endpoint GET /employees (current versions)  Endpoint GET /contracts (all versions)  Endpoint GET /persons (all versions)  Endpoint GET /organizationUnits (all versions)  Endpoint GET /sickleaves (all versions)  Endpoint GET /maternityleaves (all versions)  Endpoint GET /jobprofiles (all versions)  Endpoint GET /roleassignments (all versions)    How to ‘match’ entities? As a user, you are able to ‘match’ corresponding datasets, based on entity-specific unique identifiers. These specific keys per entity are unique and do not change during time.

  Swagger documentation The following swagger page gives an overview of the endpoints: Recruiting API   Endpoints Candidates Post  candidate The endpoint   Post  candidate   allows to send a candidate to be hired in the core system. This method returns the processId to check the status. POST https:// api.youserve.nl /recruiting/v1.0/candidates There are 2 ways of calling this endpoint, with or without attachments. With attachments The header Content-Type should be: multipart/related; boundary="A100x"; (The boundary is the one you choose). The total size among all files is up to 4MB and the allowed file types are pdf, docx and txt. The body should be splitted by sections, being the first one a json section with the candidate data as in the request without attachments. For each attachment, there will be 2 sections: json section: name of the file --A100x Content-ID: <content> Content-Type: application/json { "Description":"contract.pdf" } file section: content of the file --A100x Content-ID: <content> Content-Type: application/pdf %PDF-1.7 %·¾¬ª 1 0 obj <<   (this example is not complete) Process status After the candidate is posted to the API, the process can be followed with the status endpoint. The status of a process could be Pending, InProgress, WaitingOnValicare (if it is configured), Completed or Failed. Replace the ProcessId in the URL with the   processId   from the previous API call. GET https:// api.youserve.nl /recruiting/v1.0/candidates/{ProcessId}   Checking the status of the hire is needed, because failed hires won’t be automatically reprocessed. It is necessary to correct the problem and send them again. Also it is possible to get a list of processes, filtering by status, created after and created before. GET https:// api.youserve.nl /recruiting/v1.0/candidates/status GET https:// api.youserve.nl /recruiting/v1.0/candidates/status?status=Completed GET https://api.youserve.nl/recruiting/v1.0/candidates/status?createdAfter=2021-09-01&createdBefore=2021-09-12   Vacancies DRAFT ⚠️   This is a draft endpoint .  Vacancy data cannot be exposed at this moment. Please reach out to our community for   more info.    GET  vacancies The endpoint   GET vacancies   gives a list of vacancies of the tenant. This endpoint is available only with mock data for the sandbox tenant. GET https:// api.youserve.nl /recruiting/v1.0/vacancies   Postman collection and environment As attachment you can find a zip file with the collection and the environment.    

Endpoints: File API: [GET] getFile The endpoint GET getFile gives tenants data in a zip (with multiple CSVs inside) or a single CSV file to a reference date. Data in CSVs are defined in the HRCB application. Data are stored periodically (once a day at 05:00 AM see also disclaimer), by our scheduler since the first introduction of the referred tenant. A name of the file is defined as "{date}_{tenantId}_{language}" in zip files (2022-05-13_123456_EN.zip) and as "{date}_{tenantId}_{language}_{groupName}" in CSV files (2022-05-13_123456_EN_Company_basic.csv). Response content type is based on the type of file: zip: application/x-zip-compressed CSV: application/octet-stream    If the file does not exist, it returns 404 (NotFound). This endpoint has required and optional query parameters.  If the required parameter is missing, it returns 400 (BadRequest). Parameter Description Required/ Optional Example Language Defines the language of the file. Supported languages:  EN NL Required EN Group Defines an exact type of the file and returns a CSV file. The content of a group is defined in HRCB application. When the group parameter is not set, then the endpoint returns a zip file that contains CSV files. Optional Company   Examples: Each request needs to have an "Authorization" value in the headers. https://api.youserve.nl/yds/file?language=en https://api.youserve.nl/file?language=en&group=Company   Client Header: The application needs to be authorized by the corresponding Tenant (HR Core Client) in order to consume the API. This is ensured by a header parameter 'x-raet-tenant-id' and the value is a tenant id that customer requests data for.   Escaping within CSV file - escape double quote character " to "" (two times double quote) - enclose the whole field value with double quote character " in these cases:    -- escaping of double quote occurred    -- field contains delimiter (character | in our case)    -- field starts or ends with a whitespace character    -- field contains newline (any of CR LF characters)   example: field one|"escaped field due to character "" present"|field three|"field with | pipe character"|"  leading and trailing whitespaces  "|no whitespaces   Disclaimer: For the time being, due to it is a newly launched product. Endpoint can be accessed throughout the day and triggers the most actual state of configuration and data instead of one file made ready once a day on 5 AM, so that the configuration settings can be tested by our users

  The Learning API is intended for Learning Management systems and allows you to: Read employees and organizational structures from Youforce to update the learning system Upload certificates to the Youforce Personal File system of the customer Domain model     Concepts Employees The object employee contains all personal and employment details of an employee. Object attributes An employee is a person with one or more employments. Attributes person details Attribute Description id Unique id for the Person row within the tenant personCode The logical person code of the employee Initials The initials of the employee. firstNames The official given names of the employee as stored in the HR Core system KnowAs The name which is used by the employee as his first name lastNameAtBirth The last name at birth of the employee. Also known as the family name lastNameAtBirthPrefix The prefix of the last name at birth lastName The last which is currently used  by the employee as his last name lastNamePrefix The prefix of the last name as used currently  nameAssembleOrder Code of the assemble order that the core system uses for the last name. The assembly order is depending on the core system and the logic behind it. partnerName The partner last name partnerNamePrefix The prefix of the partner last name titlePrefix The formal title which will be used as a prefix before the name like Doctor, Professor, et cetera titleSuffix The formal title which will be used as postfix after the name like MSc or Master of Science gender Gender of the person. Supported values are Male / Female. Note: other type of genders will be shown as Not Known birthDate Date of birth deceased Indicated if the employee deceased  UserUID Digital Identity of the user from the portal emailAddresses type address List of the addresses of the employee.  The fields are: type like Business, Private, et cetera address Addresses type street houseNumber houseNumberAdditional locationDesignation postalCode city region country List of the addresses of the employee.  The fields are: type like Home, Post, et cetera street name house number house number additional Location designation Postal code City Region Country code phoneNumbers type number list of phone numbers of the employee type like Business, Home, Mobile, et cetera number communicationLanguage Communication language   Attribute employment details Attribute Description employeeID Technical and unique id. the Id is unique within the entity and tenant. employeeCode Code of the employee employmentCode Logical code of the employment company Unique (alphanumeric) identifier of the company  with which the contract is concluded hireDate The hire date of the employment dischargeDate The end date or discharge date of the employment. originalHireDate The first hire date or original hire date of an employee within the organization. employmentType Type of employment with a short name for type like Internal employee, contractor, "Wachtgelder" jobProfile job profile code of the employment The job profile is a code that refers to the entity job profile organizationUnit organization unit of employment. The organization unit is a code that refers to the entity organization units workingAmount amountOfWork unitOfWork periodOfWork Work amount of employment.  The amount of work Unit of work that specifies the amount of work like "hours", "days", et cetera Period of work like "week" or "month" contractType Contract type of the employee. It is the code that refers to the entity contract type. costCenter Main cost center associated with the employee. It is the code that refers to the entity cost center. classification Classification of the employee. It is the code that refers to the entity Classification. location Location of the employee. It is the code that refers to the entity location. salaryScale Salary scale of the employee. It is the code that refers to the entity salary scale   Data mapping Attributes person details attribute HR Core Business personId Technical id of the employee in HRCB personCode 7014 - Uniek Persoonlijk ID (UPI) (If it is not filled in then the Medewerkercode - 22) Initials 25 - Voorletters firstNames 51 - Voornamen KnowAs 165 - Roepnaam lastNameAtBirth 24 - Achternaam lastNameAtBirthPrefix 26 - Voorvoegsel lastName 524 - Opgemaakte naam aanhef Note: In HRCB this field is combination of the   last name   and   the   last name prefix lastNamePrefix #NA nameAssembleOrder 28 - Eigennaam code partnerName 27 - Naam Partner partnerNamePrefix 166 - Voorvoegsel Partner titlePrefix 94 - Titel voor titleSuffix 95 - Titel na gender 36 - Geslacht Mapping details: 1 or Man →   Male 2, Vrouw, Woman →   Female Other values will shown as   Not Known birthDate 35 - geboorte datum deceased Based on the date of deceased. If the employee is deceased the boolean is set to   True 10302568 - Datum overlijden UserUID 10523564 - PING ID emailAddresses type address Business : 7212 - E-mailadres Prive: 7213 - E-mailadres Prive Addresses type street houseNumber houseNumberAdditional locationDesignation postalCode city region country Home: 391 - straat 392 - Huisnummer 393 - Huisnummer toevoeging 8099 - Locatie omschrijving 394 - Postcode 395 - Woonplaats 34 - Woonland   10205283 Regionaam Buitenland  Postal: 7572 - Straat Postadres 7573 - huisnummer Postadres 7574 - Huisnummer toev. adres 8100 Locatie omsch Postadres 7575 - Postcode Postadres 7576 - Plaats Postadres 7571 - Land 8101 Regionaam Buitenland phoneNumbers type number Home : 7376 - Telefoonnummer prive Mobile : 7377 - Telefoonnummer mobiel Business : 7374 - Telefoonnummer intern addresses   communicationLanguage   10   Attribute employment details Attribute HR Core Business employeeID technical ID of the employee in HRCB employeeCode 22 - Medewerkercode employmentCode #NA company 18 - company code   hireDate 39 - Datum indienst dischargeDate 10520479 - Geplande laatste datum indienst originalHireDate 308 - Datum indienst organisatie employmentType 7393 - Type Medewerker jobProfile 97 - functie organizationUnit 6000 - Organisatorische eenheid workingAmount amountOfWork unitOfWork periodOfWork amount of work = 465 - Uren periode    perodOfWork = 463 - Dagen / uren per  *HRCB supports only amount of work in "hours" parttimePercentage is not available contractType contract type = 10204687 costCenter cost center = 53  classification classification = 474  location location = 75 salaryScale salaryScale = 10300574   Users The object User contains the User Identity for Single Sign-On. The User Identity is stored in the User Management System of the Youforce portal and can be used to support Single Sign-On. For HR Core Business the User Identity is already part of the employee endpoint. Object attributes attribute example description id c7e230db-2a7f-4ef0-ad1d-9d30e7d94a2f User Identity of the employee for Single Sign On. sourceId XX123456 not relevant within the learning domain identityId null not relevant within the learning domain   Organization units The object Organization Units will provide all HR Data regarding the organization structure, like business Unit, department. Next to that, it describes in what way these are related to each other. Based on the organizational structure it’s clear ‘which' department is responsible for 'what’. Object attributes The organization unit and the role assignment how the organization is structured and who is responsible in which role.   Attributes Organization Unit Attribute Description id Unique Id of the organization Unit shortName Logical code of the organization Unit fullName Logical name of the organization Unit parentOrgUnit Id of the parent organization Unit In some core systems this relation can changed in during the timeline of an organization Unit. organizationUnitType Type of organization Unit managerId Manager of the organization unit* *Only for HR Core Business. For HR Core Beaufort the manager is part of the role assignment   Attributes Role Assignment Attribute Description id Unique Id of the record OrganizationUnitId Id of the organization unit the role assignment is effective for roleCode Code of the role. For instance the role manager is identified with the role code MGR. personCode Person who have this role for the specific organisation unit. The person code is a reference to the Person code in the employee personId Person who have this role for the specific organisation. The person id is a reference to the Person id in the employee table startDate Start date from which the role assignment is valid for that employee endDate End date from which the role assignment is valid for that employee   Data mapping Attributes Organization Unit Attribute HR Core Business id Technical id from HRCB   shortName 548 - code OE fullName 549 - Naam OE parentOrgUnit technical id of the parent Org unit organizationUnitType #N/A managerId 7137 - manager   Attributes Role Assignment Attribute HR Core Business id Technical id from HRCB   OrganizationUnitId 548 - code OE roleCode 549 - Naam OE personCode #N/A personId Reference to the Person Id startDate #N/A endDate #N/A   Job profiles Object attributes The object job profile contains the following attributes. Attribute Description shortName short name of the job profile fullName full name of the job profile jobFamily job family to which the job belongs.   Data mapping Attribute HR Core Business shortName Functie code fullName functie naam jobFamily Job family   Companies Object attributes The object company contains the following attributes. Attribute Description id identifier of the company code company code fullName full name of the company ValidFrom Start date of the version of the company ValidUntil End date of the version of the company Data mapping Attribute HR Core Business (Supported level: Client) id mutkey code company code fullName company name   Contract types Object attributes The object contract type contains the following attributes. Attribute Description code contract type code fullName full name of the contract type ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: System) code contract type code fullName contract type name   Employment types Object attributes The object employment type contains the following attributes. Attribute Description code employment type code fullName full name of the employment type ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: Client) code employment type code fullName employment type name   Cost centers Object attributes The object cost center contains the following attributes. Attribute Description code cost center type code fullName full name of the cost center ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: Client) code cost center code fullName cost center name   Classifications Object attributes The object classification contains the following attributes. Attribute Description code classification code fullName full name of the classification ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: Client) code classification code fullName classification name   Locations Object attributes The object location contains the following attributes. Attribute Description code location code fullName full name of the location ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: Client) code location code fullName location name   Salary scales Object attributes The object salary scale contains the following attributes. Attribute Description code salary scale code fullName full name of the salary scale ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: Client) code salary scale code fullName salary scale name   Job families Object attributes The object job family contains the following attributes. Attribute Description code job family code fullName full name of the job family ValidFrom Start date of the version ValidUntil End date of the version Data mapping Attribute HR Core Business (Supported level: System) code job family code fullName job family name   File upload With the documents endpoint files, certificates and other documents can be uploaded for an employee to the Visma Personal File System (Personeelsdossier).   Asynchronous file upload Learning systems can upload files, like certificates, diplomas for individual employees to the Personal File System of Visma Raet. The file upload is an a-synchronized process. After the file is uploaded the consumer will receive a ticket Id, which can be used to monitor the process of the file upload.        

Within API for BI systems there are CSV files. These files contain 2 major components, that is the ID and ParentID collumn.    In the attachment you can see the key elements (Entities) with their respective ParentID. This knowledge is necessary for knowing the relations between the key elements (Entities).   Attachment is stored as txt file, but it can be downloaded and converted to .json.

  To get access to our Youforce resource you need to be a partner of Visma | YouServe. We have a Partner Program with different levels: Access partner Collaboration partner Software partner 1. Access partner With Access partner, we focus on Integration only. Our aim is to increase customer satisfaction and create a great user experience for our mutual customers.   As Access Partner you are able to add value to your software because of the integration you have with Visma | YouServe. You will be listed on our Website and in our Marketplace giving you exposure to more than 10.000 Visma | YouServe clients that serve more than 1.2 mln users.   Do you want to get more information on becoming an Access Partner, please contact Thomas Huisman   2. Collaboration partner With Collaboration partner, we engage in collaborations in our ecosystem with renowned vendors that add specific value to the Visma | YouServe portfolio and have a large footprint in their market.   As a collaboration partner, you will not only integrate with Visma | YouServe software but also be presented as a preferred supplier of Visma | YouServe and be part of our marketing campaigns. We will recommend each other and If the recommendation results in a sale a referral fee is applicable.   Do you want to get more information on becoming a Collaboration Partner, please contact Thomas Huisman     3. Software partner Software partners are vendors that, for various reasons, are of strategic value for Visma | YouServe and need to be integrated into the Visma | YouServe portfolio as part of the ‘one-stop-shop’ approach of Visma | YouServe.   Customers will sign a contract for the partner software via Visma | YouServe. Visma|YouServe will also service the partner software via the Service Centre and implementation of the software will be executed by our Customer Success organization.   Software partners are deeply integrated with the Visma | YouServe software. Visma | YouServe is also the reseller of the software (sometimes white labeled). A joined Sales & Marketing program with pipeline reviews will be part of the Governance as well as frequent alignment on the Roadmap of the partner software.   Do you want to get more information on becoming a Software Partner, please contact Thomas Huisman 

Getting Started! Do you want to start using one of the Domain APIs? Please read more about how to, in this Article

Versions of the endpoint employees For the endpoint   GET   /employees there’ll be 2 versions available (status : sep ‘20).   These versions are ‘header based’ available for API consumers.  The version is added to the header of the request: Example requesting v2.0 using postman   The functional difference between those versions is the following : V1 ( DEPRECATED! ) In this endpoint version we face a small issue that an employee in core system HRCB (r1) becomes a single employee in our MLM API output. As a result that a single person is returned multiple times in our API’s (see example below). Eventually this version will be phased out! Person: { personID : 123, name : Jan Jansen, address : ABC, contract : A1, validFrom : 01-02-2020, validUntil : 10-04-2020 } Person: { personID : 123, name : Jan Jansen, address : DEF, contract : B1, validFrom : 11-04-2020, validUntil : 10-06-2020 } Person: { personID : 123, name : Jan Jansen, address : DEF, contract : B2, validFrom : 11-06-2020, validUntil : 31-12-9999 }   V2 In this version V2 we’ve solved the above issue in V1, so we’ll return here in a correct way the   current   version of a unique person with the   actual   contract versions. We’ve included temporality on the ‘Person level' and also on the lower ‘Contracts level', so the API consumer is able to jump into conclusions very efficiently. Scenario : standard exposure / current person versions with current contract versions Person 1: { (current version) validFrom : 01-01-2020 validUntil : 31-12-9999 personID : 123, name : Jan Jansen, address : ABC, contract : A3, (current version) validFrom : 01-05-2020 validUntil : 31-12-9999 contract : B5 (current version) validFrom : 01-03-2020 validUntil : 31-12-9999 } Person 2: { (current version) personID : 345, name : Joke van der Laan, address : HJK, contract : A2, (current version) contract : B2 (current version) } …… Person 100 { (current version) personID : 964, name : Henk de Vries, address : VDW, contract : A1, (current version) contract : B4, (current version) contract : C1 (future version) contract C - version 1 validFrom 01-10-2020 --nextlink-- In the above V2 example we expose Person 1 with personId 123 who has two contracts (A, B). Each contract has its own versions. Contract A has two historical versions and one current version. Contract B has four historical versions and one current version. Scenario : active person has only one historical inactive contract The following scenario covers again Person 832 who’s having just one contract (A) which became historical (since yesterday). The endpoint will return his actual personal details with this (historical) contract data. So in case, there is no active contract, the response will show the last active contract version (latest historical). Person 72: { (current version) personID : 832, name : Piet van de Berg, address : DDS, contract : A3 (historical version) Scenario : active person is a ‘new hire’ with one future contract In the below scenario of Person 193, who’s having just one future contract (future hire). The /employee endpoint return actual person details with his contract details. Since there is no active contract, it will return the future contract version. Person 41: { (current version) personID : 193, name : John de Jong, address : HJA, contract : A1 (future version)

  IAM API This API is intended for identity & access management systems and enabling the provisioning of users in other systems like Active Directory or IDP’s: Retrieve employee data from Youforce Retrieve organizational structures from Youforce Retrieve job profile information from Youforce   Model   Pagination The IAM API supports pagination with the help of a nextToken. With the help of the following properties:   dateTime ,   validFrom   and   id   a “bookmark“ is generated ensuring no records are “lost“ when skipping through pages. Below a breakdown of the nextToken url generated at the end of the response body.     Next page token   - Token generated at the end of the resultset page Date timestamp   - The date timestamp of the last record of the result set page validFrom   - The   validFrom   of the last record of the result set page Id   - Primary key of the last record of the result set page.   Person layer in HR Core Business An additional requirement to use the Persons endpoint: the Person layer   needs to be enabled in HR Core Business. 

  Swagger documentation The following swagger page gives an overview of the endpoints: Payroll API   Endpoints Employees Full load or initial load To get the list of employee basic data of a tenant, the endpoint can be used without any additional parameters. GET https:// api.youserve.nl /payroll/v1.0/employees   Incremental load To get the list of employee basic data of a tenant after a specific time, the changedAfter parameter should be included. Also it is possible to include the changedUntil parameter. GET https:// api.youserve.nl /payroll/v1.0/employees?changedAfter=2020-05-19   Get employee by Id It is also possible to retrieve the data of a specific employee. GET https:// api.youserve.nl /payroll/v1.0/employees/13161246   Employee benefits Full load or initial load To get the list of employee benefits of a tenant, the endpoint can be used without any additional parameters. GET https:// api.youserve.nl /payroll/v1.0/employeeBenefits   Incremental load To get the list of employee benefits of a tenant after a specific time, the changedAfter parameter should be included. GET https:// api.youserve.nl /payroll/v1.0/employeeBenefits?changedAfter=2020-05-19   Employee fixed payments Full load or initial load To get the list of employee fixed payments of a tenant, the endpoint can be used without any additional parameters. GET https:// api.youserve.nl /payroll/v1.0/employeeFixedPayments   Incremental load To get the list of employee fixed payments of a tenant after a specific time, the changedAfter parameter should be included: GET https:// api.youserve.nl /payroll/v1.0/employeeFixedPayments?changedAfter=2020-05-19   Employee one-off payments Full load or initial load To get the list of employee one off payments of a tenant, the endpoint can be used without any additional parameters. GET https:// api.youserve.nl /payroll/v1.0/employeeOneOffPayments   Incremental load To get the list of employee one off payments of a tenant after a specific time, the changedAfter parameter should be included. GET https:// api.youserve.nl /payroll/v1.0/employeeOneOffPayments?changedAfter=2020-05-19   File upload POST  employees/ {employeeId} /paylips Endpoint for uploading a payslip to the Personal File System of Visma Raet. The endpoint returns a   ticketId   . The document will be uploaded using the type of document provided in the request, or setting a type of document by default for that customer. If this document type is not provided, then the default ovSalaris is used. The API will automatically upload the file to the Personal File System. This is an asynchronized process with an automatic retry mechanism in case the file systems is not available. The retry mechanism will try to upload the file in a maximum of 6 hours. After this period the file will be rejected with a message. Also if the file is too big (maximum 4 Mb) or isn’t a PDF file, the upload will be rejected.   GET  payslips/ {ticketId} /status Endpoint for getting the status of the uploaded file. The endpoint will return the status of the file. After the file is processed successfully the status   Complete   is returned.   Postman collection and environment As attachment you can find a zip file with the collection and the environment.  

 

 

  Q: How can I receive only changed records? A:  The   From   and   To   filter is available to receive changes in a given time range. The From and To filter option is available on most endpoints, except valueLists. Example employees:  Returns (active) employee records that have changed within the provided date-time range.   https://api.youserve.nl/iam/v1.0/employees?from=2021-01-01T09:00:00.000Z &to=2022-01-10T14:00:00.000Z   Q: What does the 90 day retention policy signify? A:  At current, the retention policy on the data stored in for the IAM API is 90 days. Based on the following properties a record will be removed when the date defined for these properties is greater than 90 days in the past: validUntil   - all entities dischargeDate   - employments, employees endDate   - role assignments, assignments Q: Why do I see records with the with dischargeDates or endDates in the past? A: We support the notion of retroactive changes i.e. when a dischargeDate for an employment or endDate for an assignment is defined today for a date is set in the past. This can be the result of an administrative mistake. In this scenario, the record will remain available for 90 more days based on the mutation date (date when the change was made).   Q: Why do I not see all the properties mentioned in the data mapping document in my response? In the IAM API properties that do not have values defined in the core systems are hidden. For this reason there might be a different amount of properties available per record.   Q: What are extensions? A: Extensions are based on the customer-specific fields defined in the core application. These custom fields can be configured and returned as part of the API response body . As a customer I have a custom field named: “height“. As part of my integration it is important to know the height of my employees in order to validate their identity. With the extensions feature we are able to expose this field and value as part of the API response allowing the customer to validate the identity of employees with the help of their height. Extensions are only available for HR Core Business and for the Employees (employee entity) and Employments (contract entity) endpoint.   Q: Why do I have more than 1 record for my entities? A: As part of the IAM API we support support, historic, current and future changes. A change in the core is reflected by a new record in the IAM API, which can be referred to as “versions“. Each record has the following properties: validFrom - This reflects the date from which a record is considered valid, the “start date“ of the validity validUntil - This reflect the date from which a record is no longer valid, it’s “end date“ of the validity    

What is the YouServe API? Through the YouServe API you can in integrate data and therefore giving your customers: an up-to-date list of the latest HR information in your application automatic on- and off-boarding of employees in your application HR Core system There is always an HR Core system in the centre of every customer implementation storing the employee data. With the API's we support  HR Core Business.   API library You can find the APIs at https://developers.youserve.nl/api-library