Knowledge base YouServe API's

  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. 

Overview of all IAM endpoints including Swagger.

  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   

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

API Statuses Concept APIs with this status are still under development and the development team is still making changes. Only a sandbox is available to start testing and the API cannot be used with customer environments.  Controlled Available (CA) APIs (or API versions) with this status are not ready yet to be rolled out to the complete customer base: It is available to a few access partners Connections of an access partner to the customer environment (tenant) are put on a waiting list, and it will take time before the connection is accepted There can be functional limitations of these APIs Controlled Available APIs have the usual security and support level. General Available (GA) APIs (or API versions) with this status are available to all access partners. The API can be used by all customers who use any of the HR Core systems that are supported by this API. Deprecated The API (or API version) is being phased out. We do not accept any new connections on this API (version). We will ask our access partners to move to another interface API. See also your Service Level Agreement   Life cycle policy We aim to provide you with a policy for releases and support for older versions for a consistent and predictable experience. Different types of changes The life cycle of any API products has dependencies on underlying products. Changes in those products may require changes to the API to support it. We distinguish between breaking changes and non-breaking changes. A breaking change is one that breaks the contract an API consumer depends on, either by a change in structure, behaviour or semantics. The release and support strategy makes a clear distinction in how these are managed. Major releases At times Visma YouServe may need to make larger changes to the API. Reasons may be changes to legal requirements, adding a large new feature to the API or an change in other products the API depends on. In these cases Visma YouServe may create a new major release of the API. We strive to also keep major releases backward compatible as much as possible but this may not always be possible. In case of breaking changes In general Visma YouServe aims to have a maximum of one major release per year. Each major release will be supported for at least 12 months after releasing the next major version. As a client to our API you will have to adjust your software to follow the major releases of our API as they will impact your integration. You must update your software to support the new API version as older API versions will be decommissioned following the policy as outlined above. Minor releases A minor release will never contain breaking changes, the are used to deliver incremental changes. Minor versions will not be visible in the path of the API. Visma YouServe can install minor updates in the standard release windows or as part of a hotfix and will communicate the changes as part of the release notes. Since this does not impact any existing functionality, we do not provide side-by-side support for multiple minor versions of the same major version: a minor upgrade just replaces the previous version. As a consumer of the API it is up to you to decide if you start using the newly available features. Announcing major releases Each release of a major API version will be accompanied by communication about the support lifecycle of the current version in the release notes. When approaching the sunset-date for an API product, we will actively reach out to inform any customers still using it: Communication When Where Recipient Announcement At the release of the new major version. Includes the date of decommissioning the previous version. General release notes All recipients of general release notes.   At the release of the new major version. Includes the date of decommissioning the previous version. Developer community Users of the Develope community 1st notification 6 months prior to decommissioning   Designated API contact persons 2nd notification 3 months prior to decommissioning   Designated API contact persons 3rd notification 1 months prior to decommissioning   Designated API contact persons     Spike arrest details Spike arrest is the way we protect against traffic spikes. Our APIs and backend can handle a certain amount of traffic, and the Spike Arrest policy smooths the traffic to the general amounts. Spike Arrest’s behaviour differs from what you might expect to see from the literal per minute values. Our default spike arrest is set to 100pm (100 requests per minute). That does not mean you can do 100 requests inside a 1-second. Spike Arrest smooths the number of full requests in a minute by dividing it into smaller intervals: Per-minute rates get smoothed into full requests allowed in intervals of seconds. For example, 100pm gets smoothed like this: 60 seconds (1 minute) / 100pm = 0.6-second intervals, or 1 request allowed every 0.6 seconds. A second request inside of 0.6 seconds will fail. Also, the 101st request within a minute will fail. When you exceed the policy, the API will return response code '429 - Too many requests' and you have to wait for the next time window.

  This API is intended for recruiting systems and allows them to get the data needed for the recruiting process and send the candidate to be hired.   Candidates Technical flow The candidate endpoint is asynchronous: The recruiting sends in the new hire or contract change. Youforce will Validate the incoming data Trigger Id Scan (optional) Start a process based on configuration of the customer The recruiting system checks if the hire has been accepted. Steps 3 is critical. The process is only accepted by Youforce when the status is 'Completed'. It is the responsibility of the recruiting system to check if the hire is successfully trigged by based on the entered data. There are no user feedback mechanisms in Youforce that inform a hiring manager that the new hire has not been accepted by Youforce.   Candidate data Property Description Mandatory Example Data type candidateID The ID of the candidate in the recruiting system. This field is available as free field in the Core for Reporting purpose. Yes 0001 string PersonData Fields related to the person       PersonalDetails: last name, first names, date of birth, etc       PhoneNumbers: list of phone numbers One is mandatory     emailAdress: Private email address to contact the candidate. Yes candidate@private.com string Addresses: list of addresses       PersonalDetails Fields related to personal data         lastNameAtBirth: The last name at birth of the candidate. Also the family name.     string   lastNameAtBirthPrefix: The prefix of the last name at birth.     string   knownAs: The name which is used by the candidate as his first name.     string   initials: The initials of the candidate.     string   firstNames: The official given names of the candidate.     string   lastName: The last name the candidate is currently using.     string   gender: The gender of the candidate.   (0) Not known (1) Male (2) Female (9) Not applicable To use 0 and 9 values, they must be configured in the core system. string   birthDate: Date of birth of the candidate.     DateTime   birthPlace: The place of birth of the candidate.     string   birthCountry: The country of birth of the candidate.     string   primaryNationality: The nationality of the candidate.     string   titlePrefix: The formal title which will be used as a prefix before the name.     string   titleSuffix: The formal title which will be used as suffix after the name.     string   maritalStatus: The marital status of the candidate.     string   lastNamePreference: A code that indicates the preferred last name of the employee. for instance last name at birth last name partner last name partner + last name at birth last name at birth + last name partner     string   lastNamePartner: The partner last name.     string   partnerNamePrefix: The prefix of the partner last name.     string   socialSecurityNumber: Social Security Number of the candidate.     string phoneNumber details of the phone number         type: home, mobile   home string   number   + 31 0624829858 string Address Fields related to the address of the candidate       type: home, postal   home string streetName: Street name   Wamberg string number: House number   69 string NumberAdditional: additional number   34 string locationDescription: location     string postalCode: Postal code   1083 CV string city: City   Amsterdam string region: Region     string country: Country   The Netherlands string ApplicationDetails Fields related with the application       vacancyNumberHR: Vacancy number in the HR Core systems. With this field the core system can check if the position is still open.   001 string vacancyNumberATS: Vacancy number in the Applicant Tracking System. This field is available as free field for Reporting purpose.   1001 string offerApproveDate: Date that the offer is approved in the ATS system. It is the date that the recruitment process ends and the onboarding of the new employee can start.   01-01-2021 DateTime NewEmployement Fields related to the new employement       payrollClient: The Id of payroll client in the core systems.   B2020 string payrollCompany: The Id of payroll company in the core system. Yes C2020 string collectiveLaborAgreement: Id of the collective labor agreement.   CAO01 string hireDate: Proposed hire date of the Candidate. Yes 01-01-2021 DateTime endDate: If the contract is for a given time, this contains the end date of the employment.   31-12-2021 DateTime contractType: Type of the contact. Yes 01 string probationPeriod: Indicates if a probation period is applied to the contract.     boolean probationPeriodDuration: Duration of the probation period.     string probationPeriodEnddate: End date of the probation period.   31-03-2021 DateTime employeeType: Type of employment like Internal employee, contractor, etc. Yes 001 string organizationalUnit: Id of the organization unit of employment. Yes OU1 string jobProfile: Job profile of the employment. Yes JP1 string establishmentUnit: The logical code of location or establishment unit where the work is performed mainly in accordance with the contractual arrangement.   EU1 string amountOfHours: Amount of working hours. Yes 40 string Salary: Fields related to the salary.       OtherBenefits: List of other benefits.       Salary Fields related to the salary       salaryType: Type of salary     string SalaryPeriodicity     string SalaryAmount     string ContractSalary     string SalaryScale     string SalaryGrade     string RPSFactor     string HourlyRateAmount     string HourlyRateScale     string hourlyRateGrade     string Benefit Fields to describe other benefits       benefitCode: Code of the benefit.   BEN01 string value: Value of the benefit.   1000 string CurrentEmployment Fields related to current employement if exists.       PersonCode: Code of the person in the existing contract.   1000250 string employmentCode: Code of the employment in the existing contract.   1 string   Vacancies DRAFT ⚠️ This is a draft endpoint. Vacancy data cannot be exposed at this moment. Please reach out to our community for more info.  Vacancy data Property Description Example Data type VacancyCode Unique vacancy number in the HR Core Self Service. This job request number is unique within the tenant. VAC0012 string Title Title of the Vacancy Case manager string organizationUnit Logical code of the organization unit HR01 string payrollCompany Logical code of the company B01 string recruitmentChannel Channel in which the recruitment systems will publish the job request. extern string jobProfile Logical code of the Job profile CMAN string jobLevel Required level of the job like instance Junior, Medior or Senior Medior string jobFamily Logical code of the Job Family HR string employeeType Type of employee Intern string amountHoursWeek Amount of hours a week 40 int contractType Contract type temporal string contractualDuration Duration of the contract. Only relevant contract type is temporal. 1 year string establismentUnit The logical code of the location or establishment unit where the work is performed, mainly in accordance with the contractual arrangement. AMS string numberOfPositionsRequired Total number of requested positions 5 int ApprovalDate Approval date of the job request 2020-12-20 DateTime startDate Start date of the job request 2021-01-01 DateTime endDate End date of the job request 2021-04-01 DateTime owner Manager of the job request J. Janssen string ownerEmailAddress Email address of the owner of the job request j.jansen@visma.com string RecruitmentReason Indicates the reason for this new position. For instance because it is new position, extension of existing position or replacement of an existing person on a position. Replacement string SalaryIndication Indication for the salary, for instance a range like: 1500 - 1800 euro or a maximum: max 2000 euro or a scale: Scale 10 Schale 10 string ExperienceLevel ExperienceLevel 4-6 string Extensions List of additional fields configured in the HSS and the API     key   string value   string   ID scan Customers can enable a Visma|Youserve ID Scan as part of their Recruiting API connections. This will increase data quality and ensure efficient administrative onboarding process. This is optional and needs to be enabled per customer.  The ID scan will complement or overwrite the data send by the recruiting system The ID scan will be triggered once the candidate has been received from our system. The candidate will receive an invite to scan his identity document and complete his data. The following data will be captured from the ID document: Birth names (incl. prefix)  Initials BSN   Nationality Birthdate Birthplace Gender Doc type Document number Document Registration Date Document Expiry Date The following data will be entered manually be the employee: Firstname to use + prefix Lastname to use + prefix Bankaccount (IBAN - minimal validation) Home address (street, number, postal, place, country) Partner last name + prefix  Title for Title after   ID Scans retention policy Successfully processed IDs will be forwarded as attachments in the triggered Hire or Contract change process in Self Service. The Self-Service retention & archiving policies are applicable for these attachments.  The service responsible for scanning the IDs will retain IDs as follows:  Successfully processed ID will be removed after 24 hours. An ID is processed when the Recruiting API has retrieved the scan from the ID scan service. Unprocessed ID will be removed after 2 weeks. So when the recruiting API was unable to fetch the ID scan for 2 weeks, the IDs will be automatically removed. 

  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, txt, jpg, jpeg and png. 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.    

  This API is intended for external payroll systems and allows them to fetch the necessary data they need to run the payrolls.   Employee basic data Property Description Example Data type isDeleted If the employee was removed in the core system true boolean customerId The code of the tenant 4024898 string companyId The id of the company 15951 string upi The unique id assigned to the employee 32789 string employeeCode The code of the employee 1079224 string employeeId The employee id in the core system 13665966 string contractId The contract id in the core system 13665965 string hireDate The hire date of the contract 2017-03-01T00:00:00 DateTime dischargeDate The discharge date of the contract 2020-12-30T00:00:00 DateTime personData List of person data versions (*)       validFromDate 2017-03-01T00:00:00 DateTime validToDate 2020-12-30T00:00:00 DateTime personalDetails (name, lastname, birthdate, prefix...)     addresses (list of addresses (home and postal))     contactInformation (personal email, work email, work number...)     extensions     lastNameAtBirth The last name at birth of the employee. Also known as the family name Vries string prefixLastNameAtBirth The prefix of the employee's last name at birth de string lastNameToUse The last name used by the employee at present Vries - Van Eijck string prefixLastNameToUse The prefix of last name used by the employee at present Van String initials The initials of the employee A.B. string firstNames The official given names of the employee Amy Beatrice string knownAs The name which is used by the employee as first name Amy string titlePrefix The title prefix of the employee Mr. string titleSuffix The title suffix of the employee Jr. string gender Gender of the employee Female string dateOfBirth The date of birth of the employee 1970-01-01 DateTime dateDeceased The date of the death 2020-01-01 DateTime? countryOfBirth The country of birth of the employee ES string placeOfBirth The place of birth of the employee Amsterdam string maritalStatus The marital status of the employee 1 string (reference list) primaryNationality The primary nationality of the employee 0001 string (reference list) nationalIdentificationNumber The national identification number of the employee 367565572 string addresses List of addresses array of objects   type Home string street Kerkstraat string houseNumber 1 string addition C string additionalInfo 2nd floor string zipCode 1234 AB string city Amersfoort string region Region string country NL string (reference list) contactInformation emailAddresses     phoneNumbers     emailAddresses List of email addresses     type Private string address p.user@example.com string phoneNumbers List of phone numbers     type Home string number +3188 123 45 67 string extensions List of custom fields     key AmountOfChildren string value 3 string employmentData List of employment versions (*)     validFromDate 2017-03-01T00:00:00 DateTime validToDate 2020-12-30T00:00:00 DateTime contractDetails     costAllocations     bankAccounts     workAmountPattern     extensions     contractNumber The contract number 1 string firstHireDate The first hire date or original hire date of an employee within the organization. 2017-03-01T00:00:00 DateTime location The location of where the employment is being performed Headquarter string contractType The type of the contract   string employmentType Code of the employment type 4 string (reference list) daysPeriod Working days in a period for the employee 5 decimal classification Classification 110001 string (reference list) jobProfile The job profile code DEV string (reference list) collectiveLaborAgreement The collective labor agreement of the company 13124836 string (reference list) organizationalUnit The organizational unit of the employee 31081923 string (reference list) terminationReason The reason of the termination of the contract REA string (reference list) costAllocations List of cost allocations     costCenter cc1 string percentage 100 int bankAccounts List of bank accounts     country NL string (reference list) iban NL62INGB1954254121 string accountOwner   string bic ABNANL2AALC string routingNumber   string accountNumber 1954254121 string bankName   string bankAccountType 01 string (reference list) currency EUR string (by default is EUR) workAmountPattern workingAmount 40 decimal workingUnit Hours string workingPeriod 1 string (reference list) workPatternId 40HoursWeek string workingPatterns (list of work pattern versions that applies to the period of the contract version)     workingPattern validFromDate 2017-03-01T00:00:00 DateTime validToDate 2020-12-30T00:00:00 DateTime days (list of workingDay)     workingDay dayIndexNumber 1 int dayOfWeek Monday = 1 enum hours 8 decimal Dependents List of dependents dependentId dependentPersonNumber dependentData: List of dependent versions     dependentId Identifier of the dependent 1 int dependentPersonNumber Person number of the dependent 10001 string dependentData List of dependent versions     prefix Van string lastName Vries string firstName Erika string gender Female string dateOfBirth 2001-01-01 DateTime dateOfDeath   DateTime relationship Partner string relationshipStartDate 2020-01-01 DateTime relationshipEndDate 2020-12-31 DateTime validFromDate 2020-01-01 DateTime validToDate 9999-12-31 DateTime extensions: List of custom fields per dependent and country     (*) The list of versions of PersonData and ContractData includes all versions, when the employee is in service and out of service.   The extensions fields in PersonData, EmploymentData and DependentData would be filled in with custom fields. No dependent data is available for German employees.   Employee benefits Property Description Example Data type IsDeleted If the employee was removed in the core system true boolean customerId The code of the tenant 4024898 string employeeCode The code of the employee 1079224 string employeeId The employee id in the core system 13665966 string contractId The contract id in the core system 13665965 string Benefits List of benefits of the employee       PayComponent HourlySalary string value 20 string validFrom 2017-03-01T00:00:00 DateTime validTo 2020-12-30T00:00:00 DateTime   Pay components included as Benefits: Pay component Element number KpiCompensation 10201240 PersonalAllowanceB 10201251 PersonalAllowanceC 10201252 PersonalAllowanceReduction 10201253 PersonalAllowanceIncludingCao 10201254 SightingFee 10201255 JobBonus 10201256 StandBy 10201257 CarAllowance 10201258 CostReimbursementTax 10201259 TravelExpenses 10204902 DivergentSalary 10300579 PersonalAllowancePercentage 10303254 HourlySalary 10518747 SalaryAmount 10302976 SalaryScale 10300574 SalaryLevel 10300575 CategorieSalaryScale 10300576   Employee fixed payments Property Description Example Data type IsDeleted If the employee was removed in the core system true boolean customerId The code of the tenant 4024898 string employeeCode The code of the employee 1079224 string employeeId The employee id in the core system 13665966 string contractId The contract id in the core system 13665965 string FixedPayments List of fixed payments of the employee       PayComponent Fixed allowance string value 10 string validFrom 2017-03-01T00:00:00 DateTime validTo 2020-12-30T00:00:00 DateTime   Pay components included as Fixed payments: Pay component Element number GrossFixedFee 10207320 InternshipCompensationNB 10207480 StaffBonus 10203907 ExpenseAllowanceUntaxed 10202687 BAdditionTaxableIncomeFixed 10207160   Employee one-off payments Property Description Example Data type IsDeleted If the employee was removed in the core system true boolean customerId The code of the tenant 4024898 string employeeCode The code of the employee 1079224 string employeeId The employee id in the core system 13665966 string contractId The contract id in the core system 13665965 string OneOffPayments List of one off payments of the employee       PayComponent Train ticket string value 17 string date 2017-03-01T00:00:00 DateTime   Pay components included as One Off Payments: Pay component Element number DailyAllowenceNet01 10206880 DailyAllowenceNet02 10206882 DailyAllowenceNet03 10206884 DailyAllowenceNet04 10206886 DailyAllowenceNet05 10206888 DailyAllowenceNet06 10206890 DailyAllowenceNet07 10206892 DailyAllowenceNet09 10206896 DailyAllowenceNet10 10206898 DailyAllowenceNet11 10206900 DailyAllowenceNet12 10206902 DailyAllowenceNet13 10206904 KilometresStatement 10204904 CAllowenceVar 10200763 AAllowenceVar 10200759   Extensions fields for German companies Person data extensions Property Example Data type SocialSecurityNumber 15090270W758 string TaxIdentificationNumber 1234562001 string Employment data extensions Property Example Data type CapitalAccumulationBenefits 2 string (reference list) CertificationOfIncreasedPensionInsurance 2 string (reference list) CertificationOfParenthood 2 string (reference list) CertificationOfPensionInsuranceExemption 2 string (reference list) ChildDaycareAllowance 2 string (reference list) ChildTaxCredit 1 string (reference list) CompanyCar 1 string (reference list) CrossborderWorker 5 string (reference list) DegreeOfDisability 9 string (reference list) EducationDegree 1 string (reference list) EmployeeGroup 1 string (reference list) EmployerFundedPension 1 string (reference list) HealthInsuranceType 3 string (reference list) LevelOfEducation 9 string (reference list) LimitedincomeTax 2 string (reference list) MainEmploymentAtOtherEmployer 2 string (reference list) Name Audi BKK string Place Ingolstadt string Religion 10 string (reference list) TaxGroup 1 string (reference list) TravelAllowance 1 string (reference list) Vouchers 2 string (reference list) With 3 string (reference list) WorkingAs 71394-3 string (reference list) WorkingLocation HH string (reference list) ContractType 1 string (reference list)   Extensions fields for Belgian companies Employment data extensions Property Description Example Data type Element number in HRCB LinkingTableBICCodeBelgium Linking table bic code 2 string (reference list) 10525244 StartDateLimosaNotification Effective date Limosa notification 2020-01-01 DateTime 10525245 NationalInsuranceNumberOld National Insurance number (old) 750915 4998 658 string 10525231 LanguagePayslip Salary slip language 1 string (reference list) 10525253 Flex Flex 1 boolean 10525255 IncomePartner Income of the partner 2 string (reference list) 10525252 CountryOfBirth Country of birth 2 string (reference list) 10517302 EndDateLimosaNotification End of limosa notification 2021-01-01 DateTime 10525246 NationalInsuranceNumber INSZ number 750915 4998 659 string 10517301 DegreeOfEducation Education degree 2 string (reference list) 10525254 MaritalStatusBE Marital status 2 string (reference list) 10517075 TaxCivilStatusOnEmployment Fiscal Marital status upon employment 1 string (reference list) 10519436 PrintPaySlips Print payslips 1 boolean 7707 CategoryEmployee Category of the employee A string (reference list) 10525264 ReasonForDismissal Reason for dismissal BP string (reference list) 10525248 SeniorityDate Seniority date 2020/08/14 DateTime 10525233 HierarchicalStatute Hierarchical status 1 string (reference list) 10520266 TaxStatus Tax status 1 string (reference list) 10525251 StartDateParentalLeave Start date interruption parental leave 2021/01/01 DateTime 10525234 EndDateParentalLeave End date interruption parental leave 2021/03/01 DateTime 10525235 ParentalLeave Type interruption parental leave OH string (reference list) 10525257 PercentageInterruptionParentalLeave Percentage interruption parental leave 12,00 number 10525237 StartDatePalliativeLeave Start date interruption palliative leave 2021/01/01 DateTime 10525238 EndDatePalliativeLeave End date interruption palliative leave 2021/03/01 DateTime 10525239 PalliativeLeave Type interruption palliative leave PD string (reference list) 10525258 PercentagePalliativeLeave Percentage interruption palliative leave 13,00 number 10525240 StartDateMedicalAssistance Star date interruption medical assistance 2021/01/03 DateTime 10525241 EndDateMedicalAssistance End date interruption medical assistance 2021/01/04 DateTime 10525242 MedicalAssistance Type interruption medical assistance MV string (reference list) 10525259 PercentageMedicalAssistance Percentage interruption medical assistance 14,00 number 10525243 StartDateTimeCredit Start date interruption time credit 2021/01/05 DateTime 10525261 EndDateTimeCredit End date interruption time credit 2021/01/06 DateTime 10525262 TimeCredit Type interruption time credit TV string (reference list) 10525260 PercentageTimeCredit Percentage interruption time credit 15,00 number 10525263 Contract1Type Type of contract 1 1 string (reference list) 10525766 Contract2Type Type of contract 2 2 string (reference list) 10525767 Contract3Type Type of contract 3 3 string (reference list) 10525776 Contract1StartDate Start date of contract 1 01/01/2021 00:00:00 DateTime 10525770 Contract2StartDate Start date of contract 2 02/01/2021 00:00:00 DateTime 10525774 Contract3StartDate Start date of contract 3 03/01/2021 00:00:00 DateTime 10525775 Contract1EndDate End date of contract 1 01/31/2021 00:00:00 DateTime 10525771 Contract2EndDate End date of contract 2 02/28/2021 00:00:00 DateTime 10525772 Contract3EndDate End date of contract 3 03/31/2021 00:00:00 DateTime 10525773 NumberOfDependentChildren Number of dependent children for tax purposes 1 int 10517103 NumberOfDependentHandicappedChildren Number of disabled dependent children 1 int 10517104 PartnerIncome Professional income partner 2 string (reference list) 10517076 HandicappedPartner Disabled partner 1 boolean 10517102 HospitalizationInsuranceForPartner Hospitalization insurance for partner 1 boolean 10526113 NumberOfDependentPersons Number of other dependent residents <65 years 1 int 10517105 NumberOfDependentDependent Number of other disabled residents dependent 1 int 10517106 NumberOfDependentPersonsGt65 Number of other dependents >= 65 years 1 int 10517107 NumberOfDependentHandicappePersonsGt65 Number of disabled residents dependent> 65 years 1 int 10517108 TaxRegimeBE Belasting regime [BE]     10528135 SocialSecurityReductionReasonBE Reden verlaging Sociale zekerheid [BE]     10528136 TaxReductionReasonBE Reden belasting verlaging [BE]     10528137 SocialSecurityRegimeBE Sociaal zekerheid regime [BE]     10528138 PartimeIndicationBE Deeltijd indicatie [BE]     10528139 WorkScheduleNumberBE Werkschema nummer  [BE]     10528141 PaymentMethodBE Betaalwijze [BE]     10528223 EmployeeContractBE Arbeidsovereenkomst [BE]     10528224 GroupNumberBE Groepsnummer [BE]     10528225 DentalInsurancePlus18BE Dentalverzekering +18 [BE]     10528226 DentalInsuranceMinus18BE Dentalverzekering -18 [BE]     10528227 NationalRegisterNumberProTimeBE INSZ-nummer ProTime [BE]     10528228 EMailProTimeBE E-mail ProTime [BE]     10528229 PartnerProfessioneBE Beroep echtgenote [BE]     10528231 PeopleDependentOn65InformalCareBE Personen ten laste 65+ mantelzorg [BE]     10528239 PersonsAtChargeDisabledPartnerBE Pers. ten laste: Mindervalide echtgenote [BE]     10528240 PersonsAtChargePartnerBE Personen ten laste-echtgenote [BE]     10528241 HigherValueMealVouchersBE Hogere waarde maaltijdcheques [BE]     10528242 MonthlyGrossIncomeScaleBE Barema brutoloon  [BE]     10528243 HourlyWageScaleBE Barema uurloon (chauffeurs) [BE]     10528244 SalaryLevelBE Looncategorie [BE]     10528245 HourlyWageBE Basis uurloon arbeiders [BE]     10528246 MonthlyGrossIncomeBE Maandloon bedienden [BE]     10528247 AlternativeHourlyWage2BE Basis uurloon chauffeurs  [BE]     10528248 ReasonWageIncreaseBE!! Reden loonsverhoging [BE]     10528249 ExtraAllowance1BE Distributiepremie chauffeurs [BE]     10528250 ExtraAllowance2BE Toeslag trainer chauffeurs [BE]     10528251 WorkSchemeCodeBE Werkschema code [BE]     10528252 DisabledEmployee Minder valide medewerker     10528253 TypeOfPayslipBE Type loonstrook [BE]     10528254 Regime5Or6BE Stelsel 5-6 [BE]     10528259 BirthcountryBE Geboorteland [BE]     10528257 Nationality Nationaliteit     10519287 CountryBE Woonland [BE]     10528256 FunctionLevelBE Functieniveau [BE]     10528456 DepartureReasonBE Reden ontslag [BE]     10528258 HospitalisationInsurancep18 Hospitalisatieverzekering +18 [BE]     10528431 HospitalisationInsurancem18 Hospitalisatieverzekering -18 [BE]     10528432 WorkLocation Work Location     7449 LastNameToUse Last name to use     590 NumberOfPeopleDependentOn65PlusInformCare Number of people dependent 65+ on  informal care     10528515   Dependent data extensions Property Description Example Data type Element number in HRCB DependentPersonStatus Status 1 string (reference list) 10519335 DependentPersonIsDisabled Disabled 1 boolean 10519251 HospitalizationInsuranceForChild Hospitalization insurance for a child? 1 boolean 10526114 DisabilityRate Disability rate 50 decimal 10526116 IsChildBenefitReceived Are child benefits received? 1 boolean 10526115  

  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.  

  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 manager Manager of the organization unit* *Only for HR Core Business. For HR Core Beaufort the manager is part of the role assignment managerPersonCode Person code of the manager   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.        

  Swagger documentation The following swagger page gives an overview of the endpoints: Learning API Endpoints 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/learning/v1.0/employees    GET employee by id The endpoint GET employee by id gives a list of the versions of the employee with the given id, including the personal and employment details of the employee. GET https://api.youserve.nl/learning/v1.0/employees/1    GET employee by person code The endpoint GET employee by person code gives a list of the versions of the employee with the given person code, including the personal and employment details of the employee. GET https://api.youserve.nl/learning/v1.0/employees?personcode=1001  Users GET users The endpoint GET users return user information for a single employee. For the User Identity is relevant for consumers who want to implement the Single Sign-On solution of Visma Raet. GET https://http://api.youserve.nl/learning/v0.1/users(employeeId=1005) Organization units GET organizationUnits The endpoint GET organizationUnits gives the organization structure of the tenant. It is possible to include filters by changedAfter and changeUntil parameters. GET https://api.youserve.nl/learning/v1.0/organizationUnits GET https://api.youserve.nl/learning/v1.0/organizationUnits??changedAfter=2020-10-08&changedUntil=2020-11-17    GET organizationUnit by id The endpoint GET organizationUnits by id gives the versions of the organizational unit with the given id. GET https://api.youserve.nl/learning/v1.0/organizationUnits/1   GET organizationUnit by short name The endpoint GET organizationUnit by short name gives the versions of the organizational unit with the given short name. GET https://api.youserve.nl/learning/v1.0/organizationUnits?shortName=OrgUnit1   GET roleAssignments The endpoint GET roleAssignments gives a list persons “who” are responsible in “which” Role for a specific part of the organization. It is possible to include filters by changedAfter and changeUntil parameters. GET https://api.youserve.nl/learning/v1.0/roleassignments GET https://api.youserve.nl/learning/v1.0/roleassignments?changedAfter=2020-10-08&changedUntil=2020-11-17 Job profiles GET jobProfiles The endpoint GET jobProfiles gives a list of job profiles of the tenant details of an employee. GET https://api.youserve.nl/learning/v1.0/jobProfiles Companies GET companies The endpoint GET companies gives a list of company versions of the tenant. GET https://api.youserve.nl/learning/v1.0/companies GET https://api.youserve.nl/learning/v1.0/companies?changedAfter=2020-10-08&changedUntil=2020-11-17   GET company by code and validAt The endpoint GET company by code and valid at gives the version of the company with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/companies/1000?validat=2020-10-01 Contract types GET contractTypes The endpoint GET contractTypes gives a list of contract type versions of the tenant. GET https://api.youserve.nl/learning/v1.0/contractTypes GET https://api.youserve.nl/learning/v1.0/contractTypes?changedAfter=2020-10-08&changedUntil=2020-11-17    GET contractType by code and validAt The endpoint GET contractType by code and valid at gives the version of the contract type with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/contractTypes/1000?validat=2020-10-01 Employment types GET employmentTypes The endpoint GET employmentTypes gives a list of employment type versions of the tenant. GET https://api.youserve.nl/learning/v1.0/employmentTypes GET https://api.youserve.nl/learning/v1.0/employmentTypes?changedAfter=2020-10-08&changedUntil=2020-11-17   GET employmentType by code and validAt The endpoint GET employmentType by code and valid at gives the version of the employment type with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/employmentTypes/0001?validat=2020-10-01 Cost centers GET costCenters The endpoint GET costCenters gives a list of cost centers versions of the tenant. GET https://api.youserve.nl/learning/v1.0/costCenters GET https://api.youserve.nl/learning/v1.0/costCenters?changedAfter=2020-10-08&changedUntil=2020-11-17   GET costCenter by code and validAt The endpoint GET costCenter by code and valid at gives the version of the cost center with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/costCenters/03?validat=2020-10-01 Classifications GET classifications The endpoint GET classifications gives a list of classifications versions of the tenant. GET https://api.youserve.nl/learning/v1.0/classifications GET https://api.youserve.nl/learning/v1.0/classifications?changedAfter=2020-10-08&changedUntil=2020-11-17   GET classification by code and validAt The endpoint GET classification by code and valid at gives the version of the classification with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/classifications/0001?validat=2020-10-01 Locations GET locations The endpoint GET locations gives a list of locations versions of the tenant. GET https://api.youserve.nl/learning/v1.0/locations GET https://api.youserve.nl/learning/v1.0/locations?changedAfter=2020-10-08&changedUntil=2020-11-17   GET location by code and validAt The endpoint GET location by code and valid at gives the version of the location with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/locations/1001?validat=2020-10-01 Salary scales GET salaryscales The endpoint GET salaryscales gives a list of salaryscales versions of the tenant. GET https://api.youserve.nl/learning/v1.0/salaryScales GET https://api.youserve.nl/learning/v1.0/salaryScales?changedAfter=2020-10-08&changedUntil=2020-11-17   GET salaryscale by code and validAt The endpoint GET salaryscale by code and valid at gives the version of the salary scale with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/salaryScales/1001?validat=2020-10-01 Job families GET jobFamilies The endpoint GET jobFamilies gives a list of job family versions of the tenant. GET https://api.youserve.nl/learning/v1.0/jobFamilies GET https://api.youserve.nl/learning/v1.0/jobFamilies?changedAfter=2020-10-08&changedUntil=2020-11-17   GET jobFamily by code and validAt The endpoint GET jobFamily by code and valid at gives the version of the job family with the given code and valid at the given date. If the validAt parameter is not set, then the current date is taken. GET https://api.youserve.nl/learning/v1.0/jobFamilies/DEV?validat=2020-10-01 File upload POST employees/{personId}/documents/certificate Endpoint for uploading a certificate to the Personal File System of Visma Raet. The endpoint returns a ticketId . The file will be stored in a standard folder for certificates. The name of the folder is “certificaat”. This name cannot be changed by the end-user or the API. POST https://api.youserve.nl/learning/V1.0/api/employees/1/documents/certificate The API will automatically upload the file to the Personal File System. This is an a-synchronized 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 documents/{TicketId}/status Endpoint for getting the status of the file upload. The endpoint will return the status of the file. After the file is processed successfully the status Complete is returned. GET https://api.youserve.nl/learning/v1.0/employees/documents/{{TicketId}}/status Postman collection and environment As attachment you can find a zip file with the collection and the environment.

Sandbox environment Single Sign-On Sandbox environment Q: Is there a test or sandbox environment available for developers? A: Yes, we have different a sandbox environment available. Please contact us if you want to access the environment. Single Sign-On Q: I want to use the API together with the Single Sign-On solution of Visma Raet. What should I know about that? A: For Single Sign-On you need to keep the User Identify of the employee in your system. This User Identity will be used to switch between the Youforce module and your application for a single employee.  

  General Access to the Visma|YouServe support desk When Partner first starts using the Domain API’s, Visma|YouServe will create one end-user (hereinafter: Administrator) for Partner, who is given access to the Ticket system of Visma|YouServe. An Administrator is an authorized person by Partner who uses the Domain API’s and subsequently is able to create new Administrators.  The Visma|YouServe Ticket system is accessible through this link: Log Support Ticket Service Support Questions about the functioning of Domain API’s s are answered by Visma| YouServe’s Service Center. We also process reports about malfunctions and deal with it adequately and ensure proper feedback. We offer these services to the registered, professional contact persons of Partner. The designated contact persons of Partner, are able to report detected incidents to Visma YouServe’s Service Center. This is possible via accessing the Visma|YouServe Ticket system.  In the case of escalation, you can contact us by telephone  The ticket system of Visma|YouServe  grants access and information about the progress of submitted questions and the offered solutions. Contact persons are during the support process able to add information and react to the offered solutions by Visma|YouServe. Access by telephone of the Service Center  Access by telephone of the Service Center is meant for those situations where direct contact is needed to provide a solution or in case of escalation. The Service Center can be reached by telephone on workdays between 8:00 am and 6:00 pm.  We kindly ask you to enter your partner number and to choose between the Service on which the question is related to. Our Stand-by Service can be reached by telephone outside work hours, for reports with respect to the availability of the Domain APIs. The Stand-by Service is available on workdays between 6:00 am and 8:00 am and between 6:00 pm and 10:00 pm and during weekends between 6:00 am and 10:00 pm.   Note: The Stand-by Service is only for reports on malfunctions in the availability of the Domain API’s applications and is not meant for substantive questions or for reporting other malfunctions.  FAQ Who can get support? Partners only. See How to become an Access Partner How can I log a ticket on an API on login? You will receive instructions for this as part of your access partner contract. How long does it take before my ticket is picked up? Visma | YouServe applies four Support Level Codes to give the right priority to the malfunction and the corresponding response time. The distinction in Support Level Codes is based on the type, severity, the corresponding initial response time and the expected recovery time of the reported malfunction.  Code Meaning Description 1 High The malfunction has a far-reached and immediate effect on the activities in the organization of the customer: activities cannot continue. There is no alternative solution that offers similar results.  2 Medium The malfunction has a significant effect on the activities in the organization of the customer: An alternative solution is available, whether or not with some limitations. 3 Low The malfunction has limited or no effect on the activities in the organization of the customer The following resolution times relate to the Service Level Code, depending on the Service Code Meaning Maximum duration 1 High Solution by means of a workaround 90% within 24 hours 100% within 48 hours Structural solution: Within 30 calendar days 2 Medium Structural solution: Between 30-90 calendar days 3 Low Solution The solution shall be included in the release calendar How do get a login to the support tool? You will receive instructions for this as part of your access partner contract.