1-2-2025: New functionality: reset configuration With reset configuration, you can restore the configuration to a specific date. This can be useful if a change in the configuration was not correct.   The reset configuration can be found in the menu Tools:   Read more about the new functionality in the documentation.     1-1-2025: First release of configuration tool of API for BI Systems Yes, we have a new product: a brand new tool to configure the output of the API for BI Systems. The csv files which are retrieved with the API for BI systems can be configured easily with our new API configuration application. The application is available in the YouServe Portal and via direct web address:  https://apiconfiguration.youserve.nl/ Find out more about this new tool in this article.   How to use the configurator is described in this article   ... View more

The IAM API offers a user endpoint where specific user data can be retrieved, also the identity can be patched. Check the documentation user endpoint v1 for way of working up till 1-3-2025. In user endpoint v1, the data source for the endpoint is the Youserve portal with Raet IAM and ping as IDP. We changed the source of the data to HR Core Business. This will solve current data conflicts and will be future proof when YouServe will move towards YouServe IAM with Visma Connect as IDP.   The new version of the User endpoint will be available with the url: https://api.youserve.nl/iam/v2.0/users. Getting and updating the data has slightly changed. Check the documentation of user endpoint v2 in this article.    Retrieving data: GET method The Get method will deliver more properties as version 1:  Id (pingid), sourceid (username) and identityid. businessEmailAddress (new) privateEmailAddress (new) Calling the Get method has changed. Version 1:  https://api.youserve.nl/iam/v1.0/users(employeeId={employeecode}) example: https://api.youserve.nl/iam/v1.0/users(employeeId=12345) Version 2:  In Version 2 we support retrieving the data by personCode and mutkey of employee: https://api.youserve.nl/iam/v2.0/users?personcode=1012 or https://api.youserve.nl/iam/v2.0/users/36457840 EmployeeCode is also supported, but we advice not to use this, because employeeCode is not always unique for an employee.   https://api.youserve.nl/iam/v2.0/users?personcode={personcode} example: https://api.youserve.nl/iam/v2.0/users?personcode=12345 https://api.youserve.nl/iam/v2.0/users/{id} example: https://api.youserve.nl/iam/v2.0/users/36457840  Please read all about this in the documentation of user endpoint v2.    Updating data: PATCH method Calling the Patch method has also changed. Version 1:  https://api.youserve.nl/iam/v1.0/users(employeeId={employeecode})/identity  example: https://api.youserve.nl/iam/v1.0/users(employeeId=12345)/identity  With in the request body:  { "id": "user@customer.com" }   Version 2:  https://api.youserve.nl/iam/v2.0/users?personcode={personcode} example: https://api.youserve.nl/iam/v2.0/users?personcode=12345 https://api.youserve.nl/iam/v2.0/users/{id} example: https://api.youserve.nl/iam/v2.0/users/36457840  With in the request body (same as v1):   { "id": "user@customer.com", "businessEmailAddress": "user@business.com", "privateEmailAddress": "Johnson@yahoo.com" }   Please read all about this in the documentation of user endpoint v2.    The new version of the user endpoint is available starting from February 2025.  You can move to the new version on your own pace. Both versions are active and supported. Version 1 will be deprecated by July 2025.               ... View more

Status: Solved.   Scope of issue: MLM API, WFM API.    Description of situation: Endpoints for WFM and MLM API respond with error message:  {     "message": "Client certificate invalid or missing",     "correlationId": "0HN8TCQ3BBS94:0000004D",     "issuedAt": "2024-12-16T08:10:22.4366938Z",     "errorCode": "Forbidden" } We are working on a solution. Update 16-12-2024, 12:00 - Certificates issue is still in analysis. Update 16-12-2024, 14:00 - Issue solved.   First occurrence of issue: 16-12-2024   Impact:  All customers using the MLM API and WFM API   Issue solved: 16-12-2024, 14u.   ... View more

The goal of this forum is to connect developers/users which use the YouServe APIs, directly to the YouServe development department which is designing and developing the APIs. Also, users/developers can respond to each other to share knowledge.   When you start a topic, use the correct category to address any of the APIs according to your needs.   ... View more

06-12-2024: New filetype can be uploaded to Payroll Business: Excel document To upload changes of HR Core data, we have added a new file format to the options to upload data: Excel document. This format is support with businesstype 113016. To learn more, a description of the content of the file can be found in the online help of HR Core Payroll Business. Search for the keywords: "externe mutaties" and "Excel basisdocument". To configure this type, ask your (payroll) consultant or account manager. Follow the link to have a look at a complete overview of all the filetypes. ... View more

04-12-2024: Captcha added to creation of user To protect the developer portal we have added Captcha to the registration of users.  The developer portal is a public website where anyone can create accounts. To prevent bots from creating phantom accounts, we have added an extra requirement to create an account.     28-11-2024: New look and feel The developer portal has a new look and feel. From the 28th of November we use the new yellow look and feel.  The functionality has stayed the same. Have a look at https://developers.youserve.nl.       ... View more

  The csv files which are retrieved with the API for BI systems can be configured easily with our API configuration application. The application is available in the YouServe Portal and via direct web address:  https://apiconfiguration.youserve.nl/ How to use the configurator is described in this article. Overview   Create a new file (1) To create a new file in the API for BI systems, use the green button on the right bottom. 1a) The entity number will always be added to the file. Example: CompanyData becomes CompanyData_17.csv   Continue to add elements (columns in the csv-file):   The number of columns in the file is limited. Please check the maximum numbers of columns in the table below: Level/ Data entity Max number of columns/ elements 90014669 (90014669) 5 Assignment 5 Child(7262) 5 Client(15) 10 ClientCla(191) 10 Company (17) 20 CompanyCar 20 CompanyCla(193) 15 ConnectionLeavePayroll 5 ContactPerson(7580) 15 Contract (49) 200 Education(7170) 10 Employee(21) 140 Establishment (7449) 30 Establishment_824 5 Evaluation 5 Experience(7157) 5 FormationPlace 5 Function(97) 5 FunctionInformation 5 Gatekeeper 10 GatekeeperAction 5 IncomeRelationship 25 IndividualLeaveRights(7701) 10 Knowledge 5 LeaveBalance 5 LeaveRequest 10 LeaveRequestDetails 5 MaternityLeave(7593) 10 MedicalLeaveManagement(7471) 20 OrganizationalUnit(6000) 15 OrgUnitWorkLocation 5 Person (821) 10 ProcessingUnit 5 ReductionLeaveRights 5 RoleAssignment 5 TemporaryWorker 5 TradeMagazine 5 Trainee 15   A newly created file will be available in the next creation of the csv files. This is done once a day between 00:00 and 5:00 in the morning.   Change/Copy a file (3) You can change the columns of the csv-files. If elements/columns are added, they will always be added to the end of the columns in the csv -file.   The copy (clone) function will allow you to make changes without immediate effect on your process after you have downloaded the files. For instance: you want to add some fields and want to test first. Take the next steps: Copy the current file with the name CompanyData_17, give a new name. For instance:  CompanyDataV2_17 Open the configuration of CompanyDataV2_17 and apply the changes. The next day, the API for BI systems delivers both files: CompanyData_17 and CompanyDataV2_17 Now you can use the new file to test the process. If you are ready to start using the new file, change the current filename and rename the new file to the old filename: CompanyData_17 rename to CompanyDataV1_17 CompanyDataV2_17 rename to CompanyData_17 Once you have your process complete, you can delete the CompanyDataV1_17  file.   Changing/ copying a file will take affect in the next creation of the csv-files.    Reset configuration The reset configuration gives you the option to restore the complete configuration of all files to a chosen date. Backups can be restored from 30 days back in time.     The backup of the selected date is taken between 00:00 and 02:00 of that particular date. Be aware that changes after 2AM are available in the backup of the next day!         ... View more

On 04-09-2024 a fix will be deployed to solve an issue in het clean up of data in the IAM API. Users of the IAM API can expect less data the endpoints of IAM API.   Within the IAM API, the retention time for data is configured per customer. For most customers, this is 90 days, but this can be different per customer. Contract and employee data older then 90 days will be cleaned up in the API platform after this retention time and will not delivered anymore in the IAM API. Note: this has no effect on the data in HR Core.   We noticed that the clean up of data outside retention time was not working properly for a couple of months. Employees out of service and old contract-time slices out of retention time, were still delivered. With the fix of 4-9-2024, the data outside retention is cleaned up correctly and data in IAM API is delivered correctly. This concerns the endpoints: Employees, Employments and Persons.       ... View more

Status: Solved.   Scope of issue: MLM API, WFM API.    Description of situation: Changes on sick leaves are not available in the Sickleaves endpoint. This concerns all changes, for instances new sick leave, partial recovery or full recovery. Other endpoints are correct. We are working on a solution. Update 9-7-2024, 12:10 - We are fixing the issue. We expect that incremental load will be available in the next hours for all customer. Update 9-7-2024, 13:00 - Incremental load is available for all customers.   First occurrence of issue: 07-07-2024, 5am   Impact:  All customers using the MLM API and WFM API   Issue solved: 09-07-2024, 1pm ... View more

  08-05-2024: History days on leave and leave balance data As described in the documentation of the API for BI systems, history data of max 4 years are made available.  Recently we learned that this limitation was not in place for the datatypes leave (NL: verlofaanvraag) and leave balance (NL: verlofbalans). In stead, all data was delivered.   On 15-5-2024 we will release a fix to align the history data also for leave and leave balance.   Leave After the fix only leave periods are delivered which are within scope of 4 years. If a leave period starts before the scope of 4 years, but ends after, it will still be delivered.   Leave balances After the fix only leave periods are delivered which are within scope of 4 years. Most likely, leave entitlements start on the first of January. So if data is retrieved today (8-5-2024), taken in account that leave balance starts on first of January, the leave balance of 2020 up and till 2024 is delivered.   ... View more

Status: Solved, files are available   Scope of issue: API for BI Systems.   Description of situation: Files of are not available for download. This morning exports of .csv files are not generated as normal. Clients encounter http 404 (not found) when requesting files through endpoints. We are working on a solution and expect files will be available this morning.   First occurrence of issue: 17-04-2024, 9am CET   Impact:  All customers using the API for BI Systems.    Issue solved: 17-04-2024, 10:45am CET. ... View more

  Endpoints Companies The entity Companies contains data related to the existing sub-companies within a tenant/client. https://api.youserve.nl/onboarding/companies    Filters Single company - Retrieve specific company by adding the id of the company. GET https://api.youserve.nl/onboarding/companies/<id>   Companycode - Retrieve specific company by filtering on companycode. https://api.youserve.nl/onboarding/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/onboarding/companies?ChangedAfter=2024-01-01T10:00:00.000Z&ChangedUntil=2024-06-01T11:00:00.000Z.   Format: YYYY-MM-DDTHH:MM:SS.sssZ.     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 Indicates 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 Startdate of the timeslice/version of a record. 2024-01-01 Referencedate NL: Peildatum validUntil Enddate of the timeslice/version of a record. The enddate is the (validFrom-1) of the successive version. If no successive version is available then value is 9999-12-31. 9999-12-31 2024-12-31  N/A isDeleted Provide the active/inactive status of the record in the core system. false N/A Extensions are not supported in companies endpoint.     Data mapping Fields marked with (V) should be connected with the results of the endpoint ‘Valuelists’. Employees This endpoint will return unique persons with their associated contracts.  Only the current active version of the person with its contracts is returned. If person has only contracts in the future, this will be returned. If person only has active contract in the past, the last contract is returned. Details we’ll expose are personal details, partner details, contact information, and the latest address details.    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/onboarding/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/onboarding/employees/<personId>  https://api.youserve.nl/onboarding/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/onboarding/employees?personCode=<personId>    Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request.  https://api.youserve.nl/onboarding/employees?ChangedAfter=2024-01-01T10:00:00.000Z&ChangedUntil=2024-06-01T11:00:00.000Z. Format: YYYY-MM-DDTHH:MM:SS.sssZ.   Data mapping Employee API field Description Example HR Core Business (r1) id 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 knownAs The name is used by the employee as his first name. Amy  165 - Roepnaam lastName The last which is currently used by the employee as his last name. Vries - Van Eijck  524 - Opgemaakte naam aanhef 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 emailAddresses private email address AnneMarie@privatemail.com Prive: 7213 - E-mailadres Prive validFrom Startdate of the timeslice/version of a record. 2024-01-01 Reference date / Peildatum (NL) validUntill Enddate of the timeslice/version of a record. The enddate is the (validFrom-1) of the successive version. If no successive version is available then value is 9999-12-31. 9999-12-31 2024-12-31     Contracts 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 validFrom Startdate of the timeslice/version of a record. 2024-01-01 Reference date / Peildatum (NL) validUntill Enddate of the timeslice/version of a record. The enddate is the (validFrom-1) of the successive version. If no successive version is available then value is 9999-12-31. 9999-12-31 2024-12-31   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 companyId Unique (numeric) identifier of the company 11058330 mutkey of company 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. The field will always be in the response, even if the field is not filled. 2025-12-31 10520479 - Geplande laatste 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 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 emailAddresses: type type     emailAddresses: address business email address AnneMarie@work.com Business : 7212 - E-mailadres extensions: key Extra customer specific data can be added with extensions. extensions: value   Jobprofiles This endpoint returns all the relevant data regarding the job profiles, like Job family information & Job profile descriptions. https://api.youserve.nl/onboarding/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. 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": "2024-01-01", "validUntil": "9999-12-31" "extensions": [], "id": "45", "fullName": "Functie 45", "level": "client", "isDeleted": false } Output example 2 : JobProfile on company level { "validFrom": "2024-01-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/onboarding/jobprofiles/<id>     Level - Filter out specific Job Profiles corresponding to a specific “level”. https://api.youserve.nl/onboarding/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/onboarding/jobprofiles?ChangedAfter=2024-01-01T10:00:00.000Z&ChangedUntil=2024-06-01T11:00:00.000Z. Format: YYYY-MM-DDTHH:MM:SS.sssZ.     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   123 Mutkey of jobprofile 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). Client Company   companyCode In case the 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   isDeleted Provide the active/inactive status of the record in the core system. False   validFrom Startdate of the timeslice/version of a record. 2024-01-01 Reference date / Peildatum (NL) validUntil Enddate of the timeslice/version of a record. The enddate is the (validFrom-1) of the successive version. If no successive version is available then value is 9999-12-31. 9999-12-31 9999-12-31 2024-12-31 Extensions are not supported in this endpoint.     Organization Units This endpoint will provide organization Units  (HRCore Business: "Instellingen > Formatie en Organisatie > Organisatorische eenheden"))  https://api.youserve.nl/onboarding/organizationunits   Filters Single organisation unit - Retrieve specific org unit by adding the id of the org unit. https://api.youserve.nl/onboarding/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/onboarding/organizationunits?ChangedAfter=2024-01-01T10:00:00.000Z&ChangedUntil=2024-06-01T11:00:00.000Z. Format: YYYY-MM-DDTHH:MM:SS.sssZ.   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 backupManager backup manager of org unit 4005614 7011 - Backup manager (mutkey of employee) backupManagerPersonId PersonCode of the Backup manager of the Organization Unit. 12345678 10519680 - Persoon nummer Corresponds with: Endpoint: Person, Property: personCode validFrom Startdate of the timeslice/version of a record. 2024-01-01 Reference date / Peildatum (NL) validUntil Enddate of the timeslice/version of a record. The enddate is the (validFrom-1) of the successive version. If no successive version is available then value is 9999-12-31. 9999-12-31 2024-12-31   Extensions are not supported in this endpoint.     Role Assignments The Role assignments endpoint delivers the role an employee has in the organization.  https://api.youserve.nl/onboarding/roleassignments   Filters Single roleassignment - Retrieve 1 role assignments by adding the id of the item. https://api.youserve.nl/onboarding/roleassignments/<id>   OrganizationUnitId - Retrieve all roleassignments for 1 specific organizational unit: https://api.youserve.nl/onboarding/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/onboarding/roleassignments?ChangedAfter=2024-01-01T10:00:00.000Z&ChangedUntil=2024-06-01T11:00:00.000Z. Format: YYYY-MM-DDTHH:MM:SS.sssZ.   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 employeeId Technical number for an employee 12345 mutkey of employee includingChildOrgUnits Refers to the level of authorisation of a specific role within an organisation. true / false 913 - includeChildOU 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 Extensions are not supported in this endpoint.   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/onboarding/valuelists    Filters Single type - Retrieve details of a specific type of valuelist, based on the “type”. https://api.youserve.nl/onboarding/valuelists/<type> example https://api.youserve.nl/onboarding/valuelists/employmentType   Level - Filter out specific valuelists corresponding to a specific “level”. https://api.youserve.nl/onboarding/valuelists?level=company    Combination level, type - combining the 2 above filters. https://api.youserve.nl/onboarding/valuelists/function?level=company        ... View more

  Als je een bestand wilt uploaden dan kan dat in het YouServe product waar dit bestand beschikbaar moet komen. Hetzelfde geldt voor het downloaden van bestanden. Bijvoorbeeld: Een declaratie uploaden in Self Service. Of een salarisstrook downloaden in de YouServe App.   Er kunnen situaties zijn waarbij een medeweker geen login voor een product heeft, maar wel een bulkbestand wil verwerken.  Bijvoorbeeld: een mutatiebestand voor HR Core Business (upload) of een groot aantal documenten toevoegen aan Dossier (upload) of salarisstroken downloaden vanuit Payroll Business (download). In deze gevallen kan je de YouServe File Transfer gebruiken. De YouServe File Transfer is beschikbaar via: https://filetransfer.youserve.nl. Hoe kan je bestanden uploaden? Log in op https://filetransfer.youserve.nl. Kies voor de tab Upload files.     De volgende bestanden kunnen worden geupload: Batch import bestanden voor HR Core Business (type 113001)  EMA Import bestanden voor HR Core Business (type 113002)  Batch import voor Personeelsdossier (type 107000)    Onder in het scherm kan je zien wat je al geupload hebt.   Deze bestanden blijven 30 dagen zichtbaar.    Wil je al een kijkje nemen hoe het werkt? Bekijk dan onderstaande video:     Hoe kan je bestanden downloaden? Log in op https://filetransfer.youserve.nl. Kies voor de tab Download files.   De volgende bestanden kunnen worden gedownload: Journaalposten vanuit HR Core Business (type 113003)  Salarisstroken en jaar opgaven vanuit HR Core Business (type 113014)  Betaalbestanden (SEPA) vanuit HR Core Business (type 134001)   Standaard worden de bestanden getoond die nog niet gedownload zijn. Wil je bestanden zien die al gedownload zijn of wil je nog een keer deze bestanden downloaden, dan kan je het filter bij Status aanpassen.   Het is ook mogelijk om te filteren op File Type. Bestanden blijven 30 dagen beschikbaar nadat ze zijn aangeboden.   Wil je al een kijkje nemen hoe het werkt? Bekijk dan onderstaande video:     Autorisatie De YS File Transfer is alleen beschikbaar als je hiervoor geautoriseerd bent. Per type bestand is een aparte autorisatie nodig. Wil je van dit product gebruik maken, neem dan contact op met je Service Delivery Manager of Account Manager.   Wil je geautomatiseerd bestanden uploaden of downloaden (system to system) dan kan je gebruik maken van de File API. ... View more

  Als je een bestand wilt uploaden dan kan dat in het YouServe product waar dit bestand beschikbaar moet komen. Hetzelfde geldt voor het downloaden van bestanden. Bijvoorbeeld: Een declaratie uploaden in Self Service. Of een salarisstrook downloaden in de YouServe App.   Er kunnen situaties zijn waarbij een medeweker geen login voor een product heeft, maar wel een bulkbestand wil verwerken.  Bijvoorbeeld: een mutatiebestand voor HR Core Business (upload) of een groot aantal documenten toevoegen aan Dossier (upload) of salarisstroken downloaden vanuit Payroll Business (download). In deze gevallen kan je de YouServe File Transfer gebruiken. De YouServe File Transfer is beschikbaar via: https://filetransfer.youserve.nl. Hoe kan je bestanden uploaden? Log in op https://filetransfer.youserve.nl. Kies voor de tab Upload files.   Er kunnen meerdere bestanden in 1 keer worden geupload.   De volgende bestanden kunnen worden geupload: Batch import bestanden voor HR Core (type 113001) * EMA Import bestanden voor HR Core (type 113002)  * Batch import voor Personeelsdossier (type 107000)  * Om deze bestanden te kunnen verwerken is aanvullende configuratie nodig in HR Core Payroll Business. Zie hiervoor de info verwijzing in File API bij het desbetreffende type.   Onder in het scherm kan je zien wat je al geupload hebt.   Deze bestanden blijven 30 dagen zichtbaar.    Wil je al een kijkje nemen hoe het werkt? Bekijk dan onderstaande video:   Hoe kan je bestanden downloaden? Log in op https://filetransfer.youserve.nl. Kies voor de tab Download files.   De volgende bestanden kunnen worden gedownload*: Journaalposten vanuit HR Core (type 113003)  Salarisstroken en jaar opgaven vanuit HR Core (type 113014)  Betaalbestanden (SEPA) vanuit HR Core (type 134001) * Om deze bestanden beschikbaar te stellen verwerken is aanvullende configuratie nodig in HR Core Payroll Business. Zie hiervoor de info verwijzing in File API bij het desbetreffende type.   Standaard worden de bestanden getoond die nog niet gedownload zijn. Wil je bestanden zien die al gedownload zijn of wil je nog een keer deze bestanden downloaden, dan kan je het filter bij Status aanpassen.   Het is ook mogelijk om te filteren op File Type. Bestanden blijven 30 dagen beschikbaar nadat ze zijn aangeboden.   Wil je al een kijkje nemen hoe het werkt? Bekijk dan onderstaande video:   Autorisatie De YS File Transfer is alleen beschikbaar als je hiervoor geautoriseerd bent. Per type bestand is een aparte autorisatie nodig. Wil je van dit product gebruik maken, neem dan contact op met je Service Delivery Manager of Account Manager.   Wil je geautomatiseerd bestanden uploaden of downloaden (system to system) dan kan je gebruik maken van de File API. ... View more

  18-04-2025: new property classification and new valuelist types Two new features are added to the MLM API: 1) The Endpoints Employees and Contracts are extended with the property classification. Documentation: contract endpoint  2) The Endpoint Valuelist is extended with the type classification (to support the new property) and the type department. The last one can be used if you have added the extension department. Documentation: valuelist endpoint Documentation:   04-01-2024: nextLink added to the response header Since the start of the MLM API, the nextLink tag is available in the body of the response.  To increase the easy of handling the paging, we have added the nextLink tag also to the response header of all the MLM endpoints. Please read more about his in the MLM API documentation. ... View more

Status: Solved   Scope of issue: File API YouServe. Uploads of type: all.   Description of situation: Files cannot be uploaded to YouServe using the File API. Download of files is available. But, due to the upload-issue, files you expect to be available for download are not available at the moment.   First occurrence of issue: 1-12-2023, 2:52am GMT   Impact:  All customers using the File API.    Issue solved: 1-12-2023, 11am GMT (12pm CET) ... View more

Due to mandatory technical maintenance in the MLM API and WFM API, you may experience disruptions during between 12 noon and 1pm on 26th of October 2023. If the work is completed earlier, we will let you know.   We apologize for the inconvenience. ... View more

Due to technical maintenance on 21-9-2023 on the File API, you can expect disturbance between 10am and 11am. When errors occur, please retry the file up and download after 11am. We apologize for the inconvenience.   Update 21-9-2023, 11:35.  Technical maintenance is ready. ... View more

Update (21-8-2023, 1pm) The upgrade is finished.    Original message: On the 21st of August 2023, we will upgrade our Service Gateway tooling. This will cause downtime of all our API's starting at 11am. We expect the API's to be unavailable for a few hours. When the API's are available again, we will give an update.   Q&A Why do we need to upgrade? The upgrade is mandatory while the old version from our third party will no longer be supported soon. The new version will also bring advantages to handle the backend of the APIs.   Why do we do this during office hours? We are running this update during business hours, because APIs are system to system connections, not bound to office hours. On the other hand, delivering support for migrations is much easier during office hours.   What can you do if you experience connection issues after 11am on 21st of August? Please revisit this message to check for updates. If the upgrade is not finished yet, please wait till the upgrade is finished. If the upgrade is finished and you experience connection issues, please contact our Service Desk or known communication channels. ... View more

Update (21-8-2023, 1pm) The upgrade is finished.    Original message: On the 21st of August 2023, we will upgrade our Service Gateway tooling. This will cause downtime of all our API's starting at 11am. We expect the API's to be unavailable for a few hours. When the API's are available again, we will give an update.   Q&A Why do we need to upgrade? The upgrade is mandatory while the old version from our third party will no longer be supported soon. The new version will also bring advantages to handle the backend of the APIs.   Why do we do this during office hours? We are running this update during business hours, because APIs are system to system connections, not bound to office hours. On the other hand, delivering support for migrations is much easier during office hours.   What can you do if you experience connection issues after 11am on 21st of August? Please revisit this message to check for updates. If the upgrade is not finished yet, please wait till the upgrade is finished. If the upgrade is finished and you experience connection issues, please contact our Service Desk or known communication channels. ... View more

Update (14-6-2023 1pm):  This morning the issue with the Raet File API is also resolved (https://api.raet.com/mft/v1.0). Both File API processes (Raet File API en YouServe File API) works as expected.    Update (13-6-2023 5pm):  This evening at 6pm we will roll out a fix to solve the problem with the Youserve File API (https://api.youserve.nl/fileapi/v1.0). We are still working on the problem with the Raet FileAPI (https://api.raet.com/mft/v1.0). We will give an update about the status of this issue tomorrow at 3pm.   Update (13-6-2023 2pm):  Solution is not delivered yet. Next update will be at 5pm.   Update (12-6-2023 11:15am):  Expected solution: 12-6-2023, afternoon   Original message:    Status: Solved   Scope of issue: File API YouServe and File API Raet (Youforce). Uploads of type: 113001, 113002.   Description of situation: Files with file type / Business Type: 113001, 113002 are not processed in HR Core Business.   First occurrence of issue: 7-6-2023   Impact:  Employee changes sent to HR Core business are not processed.    Issue solved: 14-6-2023 2pm   Work around: Files can be uploaded manually in the menu external mutations (NL: externe mutaties) Important: Files can be processed only once. After the issue is solved, files delivered from File API will be processed in HR Core Business. To prevent this, automatic processing needs to be stopped on customer as well as company level. This can be done in the menu: NL: Beheer > Externe mutaties > Conversieschema.   Print screen HRCB Files which are delivered after the issue is solved, can be removed in the menu item: NL: Beheer > Externe mutaties > Upload extern mutatie bestand   ... View more

  File types Sandbox file types File API Sandbox Uploads Name File API Sandbox Uploads Business type id 7100 Type Upload to YouServe Owner File API Info Type can be used to test the File API   File API Sandbox Downloads Name File API Sandbox Downloads Business type id 7101 Type Download to YouServe Owner File API Info Type can be used to test the File API       HR Core Payroll Business file types Batch Input format Name Batch Input format (EN) / Batch input formaat (NL) Business type id 113001 Type Upload to YouServe Owner HR Core Payroll Business Info File Pattern: <TENANTID>_<OPTIONAL>.<EXTENSION>   Description of this type can be found in the online help of HR Core Payroll Business. Search for the keywords: "externe systemen overzicht", and follow the "batch input" description. To configure this type, ask your (payroll) consultant or account manager. Extension can be configured per individual customer. This is customer specific. The content contains text-file. Mostly used is .dat type, but any type is possible.     CSV file (one-off mutations) Name CSV file (one-off mutations) (EN) / CSV bestand (dagmutaties) (NL) old name: Payroll EMA Imports Business type id 113002 Type Upload to YouServe Owner HR Core Payroll Business Info File Pattern: <TENANTID>_<COMPANYKEYCOD>_<OPTIONAL>.csv   Description of this type can be found in the online help of HR Core Payroll Business. Search for the keywords: "externe mutaties" and follow the "CSV bestand (dagmutaties)" description. To configure this type, ask your (payroll) consultant or account manager.     Journal entries Name Journal entries (EN) / Journaalposten Export (NL) Business type id 113003 Type Download from YouServe Owner HR Core Payroll Business Info File Pattern: RPD.<TENANTID>.*.*   Description of this type can be found in the online help of HR Core Payroll Business. Search for the keywords: "automatische journalisering". To configure this type, ask your (payroll) consultant or account manager. Extension can be configured per individual customer. This is customer specific depending on the financial application of the customer.     Excel base document ( fixed/period) Name Excel base document ( fixed/period) (EN) / Excel basisdocument (vast/periode) (NL) Business type id 113016 Type Upload to YouServe Owner HR Core Payroll Business Info File Pattern: <TENANTID>_<COMPANYKEYCOD>_<OPTIONAL>.<EXTENSION> Supported extensions: xlsx   Description of this type can be found in the online help of HR Core Payroll Business. Search for the keywords: "externe mutaties" and follow the "Excel basisdocument" description. To configure this type, ask your (payroll) consultant or account manager.       Payslips and Annual statements Name Payslips and Annual statements Business type id 113014 Type Download from YouServe Owner HR Core Payroll Business Info File Pattern: RPD.Dossier.[tenantid].[mutkey of company]00[runnr payroll]_[current date and time in 'ticks'].zip   One delivery contains: 1 zip file with the payslips or annual statements and 1 xml file which can be used as index file for the zip file. The zip file and the xml file have the same file name. Only the extension is different. To sent the files to File API, the configuration needs to be changed in HR Core Payroll Business. This configuration change is described in the online help of HR Core Payroll Business. Search for  the keywords: "Loonstroken en jaaropgeven naar File API". To configure this type, ask your (payroll) consultant or account manager.      Tax declaration / Loonaangifte file types Name Tax declaration / Loonaangifte (NL) Business type id 102000 Type Download from YouServe Owner HR Core Payroll Business Info File Pattern: DECL.[tax declaration reference number].[yyyypp].[yyyyMMdd-HHmmss].txt   Description of this type can be found in the online help of HR Core Payroll Business. Search for the keywords: "Kopie aangifte verzenden via File API ". Configuration is done per payroll tax number (loonheffingsnummer (NL)). To configure this type, ask your (payroll) consultant or account manager.     Payment manager/ Betaalmanager (NL) file types Name Payment files /  Betaalbestanden (NL) Business type id 134001 Type Download from YouServe Owner Payroll business File Pattern SEPA-[YouServe tenantId]-[messageId]-[IBAN number]-[yyyymmdd]_[hhmmss].xml   Notes: [YouServe tenantId] = unique customer number [messageId] = payment message id   example: SEPA-3333333-1286-NL72FVLB0138782523-20241008_113108.xml   Description of this type can be found in the online help of HR Core Payroll Business. Search for the keywords: "Route betaalbestand". Configuration is done per checking account (betaalrekening (NL)). To configure this type, ask your (payroll) consultant or account manager.       Personneldossier Name Personnel dossier import Business type id 107000 Type Upload to YouServe Owner Personnel dossier (PDOL) Info File Pattern: *.zip Info:  Personnel File imports documentation               ... View more

  Subscribers Subscriber is a Client Application that can list/download/delete the files of authorized business types and authorized tenants.   File list of available files This endpoint allows you to retrieve a paginated collection of the files that have been delivered to you.   In order to use this list endpoint: Create a Get request to the method’s /files URI and add the query parameter role=subscriber Example - List Available Files GET https://api.youserve.nl/fileapi/v1.0/files?role=subscriber Optional Parameters Parameter Name Value Description pageIndex integer The number of the page. (Default:0) pageSize integer The maximum number of files to return per page. Acceptable values are 1 to 1000, inclusive. (Default: 20) $filter string A query for filtering the file results. See the “Search for files” guide for the supported syntax. $orderBy string A query for sorting the file results. See the “Sort files” guide for the supported syntax.   Example - List Available Files. This example shows how to list the files that have been delivered to you. (role=subscriber) using the sandbox tenant GET/fileapi/v1.0/files ?role=subscriber &pageSize=20 &$filter=businessType eq 8000 &$orderBy=uploadDate desc HTTP/1.1 Host: api.youserve.com x-raet-tenant-id: sandbox Authorization: Bearer xxxxxxxxx If the request succeeds, the response includes a 200 OK HTTP status code, along with the paginated collection of the files that are available for you. By default, only available files are shown. (Not downloaded files). In this case, the “count” field will return the total number of available files considering the query string specified in the parameter $filter. When a file is downloaded, it will not be shown by default anymore in the list, and the “count” field will be decreased to reflect the currently available files.   Example - Response of List Available Files HTTP/1.1 200 Content-Type: application/json { "data": [ { "downloaded": false, "fileId": "d92ffb21-7938-488b-a405-bcbc9e0a9696", "fileName": "sandbox_test_file.xml", "fileSize": 107, "tenantId": "sandbox", "businessType": { "id": 7101, "name": "7101" }, "publisherId": "cfc6678d-06d8-41c7-acb5-7448a14dc917", "uploadDate": "2021-03-25T07:30:23.657Z" }, { "downloaded": false, "fileId": "c5d7438e-5c29-47e7-b518-01e5a39d6711", "fileName": "sandbox_test_file.txt", "fileSize": 33, "tenantId": "sandbox", "businessType": { "id": 7101, "name": "7101" }, "publisherId": "cfc6678d-06d8-41c7-acb5-7448a14dc917", "uploadDate": "2021-03-25T07:30:23.657Z" }, { "downloaded": false, "fileId": "f0d109df-b933-44f9-92d7-cca525ef120a", "fileName": "sandbox_test_file.csv", "fileSize": 76, "tenantId": "sandbox", "businessType": { "id": 7101, "name": "7101" }, "publisherId": "cfc6678d-06d8-41c7-acb5-7448a14dc917", "uploadDate": "2021-03-25T07:30:23.657Z" } ], "pageIndex": 0, "pageSize": 20, "count": 3 }     Search for files To search for a specific set of files, use the query string $filter to filter the files to return.   The format of the query string is: field operator values Where: field specifies the field to search upon. operator specifies the condition for the field. values are the specific values you want to use to filter your search results. Field Description Values uploadDate Upload Date according to DateTime OData format <DateTime> businessType Business Type ID <BusinessTypeId> status Status 'available', 'downloaded', 'all' fileName Name of the file <FileName> Operator Description gt Great than lt Less than ge Great than or equal le Less than or equal eq Equal ne Not equal and And or Or ( Open Parenthesis ) Close Parenthesis startsWith parameter starts with the following substring (only for FileName) endsWith parameter ends with the following substring (only for FileName) contains parameter contains the following substring (only for FileName) Query string examples What you want to query Query String Files greater than 2020-05-19T08:42:47.400Z uploadDate gt 2020-05-19T08:42:47.400Z Files greater than 2020-05-19T08:42:47.400Z and lesser than 2020-05-19T16:42:47.400Z uploadDate gt 2020-05-19T08:42:47.400Z and uploadDate lt 2020-05-19T16:42:47.400Z All Files (downloaded and available) status eq 'all' Downloaded Files status eq 'downloaded' Available Files status eq 'available' Files related to BusinessTypeID 7101 businessType eq 7101 Files related to BusinessTypeID 7100 or 7101 businessType eq 7100 or businessType eq 7101 Downloaded Files related to BusinessTypeID 7100 or 7101 status eq 'downloaded' and (businessType eq 7100 or businessType eq 7101) All Files greater than 2020-05-19T08:42:47.400Z related to BusinessTypeID 7101 uploadDate gt 2020-05-19T08:42:47.400Z and businessType eq 7101 and status eq 'all' All files with a name that starts with “payroll” startsWith(FileName, 'payroll') All files with a name that ends with “holidays“ endsWith(FileName, 'holidays') All files with a name that contains “test“ contains(fileName, 'test') All files with a name that starts with “payroll“ and a BusinessTypeId 7101 startsWith(FileName, 'payroll') and businessType eq 7101       Sort files To sort the files in an specific order, use the query string $orderBy   The format of the query string is: field modifier Where: field specifies the key to sort. Valid keys are ‘uploadDate’, ‘businessType’, ‘status’, ‘fileName’. modifier specifies the order of the sorting (‘asc’ and ‘desc’) Example usage: ?$orderBy=uploadDate asc By default, files are sorted by UploadDate desc. Note: The order in which files need to be downloaded may depend on the type of data and the way the receiving system needs to process it. See examples below: Query string examples What you want query Query String Retrieve ‘RST Functie’ files (BT: 101002. Definition of all functions/positions available in Beaufort/YouForce). You would only need the latest file so you can ignore the rest, as each file contains the complete list of functions/positions. $filter=businessType eq 101002 . In this case, the $OrderBy query string is not needed, as files are sorted by UploadDate desc by default. Retrieve employee mutations in Bint Harmony Files (BT: 101100). Based on the default settings that Beaufort/YouForce only exports the mutations instead of the full employee dataSet, it is important that you get all the new files and download them from old to new. $filter=businessType eq 101100&$orderBy=uploadDate asc       File download There are two types of downloads you can perform: Download Complete File: will download a complete file. Download File by Chunks: will download the requested bytes of a file.   Download complete file This endpoint allows you to download the files that have been delivered to you. In order to use this download endpoint: Create a Get request to the method’s /files/[fileId] URI and add the query parameter role=subscriber Add the HTTP header Accept=application/octet-stream Example - Download Request GET https://api.youserve.nl/fileapi/v1.0/files/[fileId]?role=subscriber Example - Download Available File. This example shows how to download a file that was delivered to you GET/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696 ?role=subscriber HTTP/1.1 Host: api.youserve.nl x-raet-tenant-id: sandbox Authorization: Bearer xxxxxxxxx Accept: application/octet-stream If the request succeeds, the response includes a 200 OK HTTP status code, along with the bytes of the file.   Example - Successful response of Download Available File HTTP/1.1 200 <root> <company>Visma YouServe</company> <product>File API</product> <content>Sample File</content> </root>     Download file by chunks These endpoints allow you to download chunks of files that have been delivered to you.   In order to download files by chunks you need to use these endpoints: Retrieve file size with a Head request Retrieve chunks of the file. Retrieve file size File API allows you to download chunks of files that have been delivered to you. This endpoint will be used to check if this capability is in place for the resource. Create a Head request to the method’s /files/[fileId] URI and add the query parameter role=subscriber Example - Check Available File can be downloaded by chunks HEAD/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696 ?role=subscriber HTTP/1.1 Host: api.youserve.nl x-raet-tenant-id: sandbox Authorization: Bearer xxxxxxxxx If the request succeeds, the response includes a 200 OK HTTP status code, along with the headers: Content-Length with the size of the requested file Accept-Ranges with the range unit accepted Example - Successful response of Check Available File can be downloaded by chunks HTTP/1.1 200 Content-Length:107 Accept-Ranges:bytes   Retrieve chunks of a file File API allows you to download chunks of files that have been delivered to you. Create a Get request to the method’s /files/[fileId] URI and add the query parameter role=subscriber Add the HTTP header Accept: application/octet-stream Add the HTTP header Range: bytes=firstByte-lastByte where firstByte is the first byte of the chunk you want to download and lastByte is the last one. Example - Download first 50 bytes of an Available File. This example shows how to download a chunk of a file that was delivered to you GET/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696 ?role=subscriber HTTP/1.1 Host: api.youserve.nl x-raet-tenant-id: sandbox Authorization: Bearer xxxxxxxxx Accept: application/octet-stream Range: bytes=0-49 If the request succeeds, the response includes a 206 Partial Content HTTP status code, along with the bytes of the chunk and the headers: Content-Range with the range retrieved and total file size Content-Disposition with the value attachment; filename=name of the file Example - Successful response of Download first 1024 bytes of an Available File HTTP/1.1 206 Content-Length: 50 Content-Range: bytes 0-49/107 Content-Disposition:attachment; filename=sandbox_test_file.xml <root> <company>Visma YouServe</company> <product>Fi   Not satisfiable range When the lower limit of the range is bigger than the last byte of the file, the request will retrieve a 416 error. Example - Request not satisfiable range when Download Range out of Available File bounds GET/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696 ?role=subscriber HTTP/1.1 Host: api.youserve.nl x-raet-tenant-id: sandbox Authorization: Bearer xxxxxxxxx Accept: application/octet-stream Range: bytes=107-110 The response includes a 416 Range Not Satisfiable HTTP status code, along with the header: Content-Range with the accepted range unit and the file size Example - Response - Error not satisfiable range when Download Range out of Available File bounds HTTP/1.1 206 Content-Range: bytes */107 { "correlationId": null, "message": "Range not satisfiable.", "errorCode": "416", "exception": null }     File delete This endpoint allows to delete a file you are subscribed to. This will not delete the file for everyone, just for the app that is requesting it. In order to use this endpoint: Create a Delete request to the method’s /files/[fileId] URI and add the query parameter role=subscriber Add the HTTP header Accept=application/octet-stream Example - Delete File DELETE https://api.youserve.nl/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696 ?role=subscriber HTTP/1.1 Host: api.youserve.nl x-raet-tenant-id: sandbox Authorization: Bearer xxxxxxxxx If the request succeeds, the response includes a 204 No Content HTTP status code. If the request succeeds, the response includes a 204 No Content HTTP status code. Example - Response of Delete File HTTP/1.1 204     ... View more

  Uploading files - Publishers Publisher is a Client Application that can upload files of authorized business types and authorized tenants. The uploaded files can also be listed/downloaded.   File upload Recommended usage of uploading files: Multipart upload (<100MB: The file is uploaded in a single request. (100MB max). The metadata that describes the file is also added in this request. Resumable upload (>100MB): The file is uploaded by chunks. (9MB max each chunk) The metadata that describes the file is added in the first request. Recommended usage Small files (<4 MB): Multipart upload when possible. Resumable upload and smaller chunks if you have strict response time restrictions or your network connection isn’t reliable. Medium files (> 4 MB and <100 MB): Resumable when possible and chunks of 4MB. If you have strict response time restrictions or your network connection isn’t reliable, you could use smaller chunks. Multipart when you don’t expect your files to be bigger than 100 MB (consider the file growth over time) and most of your files are small (<4 MB) Big files (>100 MB): Resumable only. When possible, use chunks of 4MB. If you have strict response time restrictions or your network connection isn’t reliable, you could use smaller chunks.   Multipart upload A multipart upload request allows you to send metadata along with the data to upload. Use this option if the data you send is small enough to upload again in its entirety if the connection fails. To use multipart upload: Create a POST request to the method’s /files URI with the query parameter uploadType=multipart. Example - POST request multipart POST https://api.youserve.nl/fileapi/v1.0/files?uploadType=multipart Add the top-level HTTP header: Content-Type. Set to multipart/related, and include the boundary string you’re using to identify the different parts of the request Example - Content-Type header Content-Type: multipart/related; boundary=foo_bar_baz Create the body of the request. Format the body according to the multipart/related content type [RFC 2387], which contains two parts: a) Metadata part. Must come first, and must have a Content-Type header set to application/json; charset=UTF-8. Add the file’s metadata to this part in JSON format. The required metadata fields are: Key Value FileName [FileName] BusinessTypeId [BusinessTypeId]   Note: For security reasons, file names have some restrictions: Filenames should fulfil the following characters sets: [a-z],[A-Z],[0-9],[-],[_],[.],[(],[)],[,],[$],[+],[`],[=],['] Malicious file extensions are not allowed b) Media part. Must come second, and should contain the bytes of the files. Identify each part with a boundary delimiter. [RFC 2046] The boundary delimiter line is defined as a line consisting entirely of two hyphen characters (“-“, decimal value 45) followed by the boundary parameter value from the Content-Type header field, optional linear white-space, and a terminating CRLF. The boundary delimiter MUST occur at the beginning of a line and it is terminated by either the header fields for the next part and two additional CRLFs, or by two additional CRLFs, in case there are no header fields for the next part. Boundary delimiters must not appear within the encapsulated material, and must be no longer than 70 characters, not counting the two leading hyphens. Example - Boundary delimiter for Metadata part: --foo_bar_baz[CRLF] Content-Type: application/json; charset=UTF-8[CRLF] [CRLF] Example - Boundary delimiter for Media part: --foo_bar_baz[CRLF] [CRLF] The boundary delimiter line following the last body part is a distinguished delimiter that indicates that no further body parts will follow. Such a delimiter line is identical to the previous delimiter lines, with the addition of two more hyphens after the boundary parameter value. Example - Boundary delimiter for last body part: --foo_bar_baz-- Send the request: Example - Send a multipart upload request using the Sandbox File Type POST/mft/v1.0/files ?uploadType=multipart HTTP/1.1 Host: api.youserve.nl x-raet-tenant-id: sandbox Authorization: Bearer xxxxxxxxx Content-Type: multipart/related;boundary=foo_bar_baz --foo_bar_baz Content-Type: application/json; charset=UTF-8 { "name":"TestFile.txt", "businesstypeid":"7100" } --foo_bar_baz This is a test file --foo_bar_baz-- If the request succeeds, the server returns the HTTP 201 Created status code along with the file’s metadata: Example - Response successful request HTTP/1.1 201 Content-Type: application/json { "id": "7ff1b498-169d-4048-8459-78f7bd7905a3", "name": "TestFile.txt", "size": 19, "creationDate": "2020-02-27T11:03:49.2033291Z", "tenantId": "sandbox", "businessType": { "id": 7100, "name": "7100" }, "numChunks": 1 } If the request fails, the server returns the HTTP 400, indicating Bad request. Example - Response failed request HTTP/1.1 400 Content-Type: application/json { "CorrelationId": "rrt-06f2e934a3cbdb710-a-de-13067-4959526-1", "Message": "Error reading body of request. Please, check all the boundaries of the request", "ErrorCode": "400", "Exception": null }     Resumable upload This protocol allows you to resume an upload operation after a communication failure interrupts the flow of data. Use this option if you transfer large files or if the likelihood of a network interruption or some other transmission failure is high   Initiate a resumable upload session and upload the first chunk of file To initiate a resumable upload session: Create a POST request to the method’s /files URI and add the query parameter uploadType=resumable. Example - Initial Post Request Resumable POST https://api.youserve.nl/fileapi/v1.0/files?uploadType=resumable Add the top-level HTTP header: Content-Type. Set to multipart/related, and include the boundary string you’re using to identify the different parts of the request. Example - Content-Type header Content-Type: multipart/related; boundary=foo_bar_baz Create the body of the request. Format the body according to the multipart/related content type [RFC 2387], which contains two parts: a) Metadata part. Must come first, and must have a Content-Type header set to application/json; charset=UTF-8. Add the file’s metadata to this part in JSON format. The required metadata fields are: Key Value FileName [FileName] BusinessTypeId [BusinessTypeId] Note: For security reasons, file names have some restrictions: Filenames should fulfill the following characters sets: [a-z],[A-Z],[0-9],[-],[_],[.],[(],[)],[,],[$],[+],[`],[=],['] Malicius file extensions are not allowed b) Media part. Must come second, and should contain the first chunk data of the file. Create chunks of a maximum of 9MB. It’s recommended to have chunks with the same size, except for the final chunk that completes the upload. The best performance using this method is achieved with chunks of 4mb. Identify each part with a boundary delimiter. [RFC 2046] The boundary delimiter line is defined as a line consisting entirely of two hyphen characters (“-“, decimal value 45) followed by the boundary parameter value from the Content-Type header field, optional linear white-space, and a terminating CRLF. The boundary delimiter MUST occur at the beginning of a line and it is terminated by either the header fields for the next part and two additional CRLFs, or by two additional CRLFs, in case there are no header fields for the next part. Boundary delimiters must not appear within the encapsulated material, and must be no longer than 70 characters, not counting the two leading hyphens. Example - Boundary delimiter for Metadata part: --foo_bar_baz[CRLF] Content-Type: application/json; charset=UTF-8[CRLF] [CRLF] Example - Boundary delimiter for Media part: --foo_bar_baz[CRLF] [CRLF] The boundary delimiter line following the last body part is a distinguished delimiter that indicates that no further body parts will follow. Such a delimiter line is identical to the previous delimiter lines, with the addition of two more hyphens after the boundary parameter value. Example - Boundary delimiter for last body part: --foo_bar_baz-- Send the request. Example - Initiate a resumable upload session using the sandbox File Type POST/mft/v1.0/files ?uploadType=resumable HTTP/1.1 Host: api.youserve.nl x-raet-tenant-id: sandbox Authorization: Bearer xxxxxxxxx Content-Type: multipart/related;boundary=foo_bar_baz --foo_bar_baz Content-Type: application/json; charset=UTF-8 { "name":"TestFile.txt", "businesstypeid":"7100" } --foo_bar_baz This is the first chunk of the file --foo_bar_baz-- If the session initiation request succeeds, the response includes a 206 Partial ContentHTTP status code, along with the upload token. Copy and save the upload token, so you can use it for uploading the next chunks of the file. Example - Successful Response of initial request HTTP/1.1 206 Content-Type: application/json { "uploadToken": "4927b6ffb51445ee982237ab6e4b3b30" } Note: The upload token expires after one hour. If the request fails, the server returns the HTTP 400, indicating Bad request. Example - Response failed request HTTP/1.1 400 Content-Type: application/json { "CorrelationId": "rrt-06f2e934a3cbdb710-a-de-13067-4959526-1", "Message": "Error reading body of request. Please, check all the boundaries of the request", "ErrorCode": "400", "Exception": null } A few checks for mitigation: Setting the right boundary definition for multipart/form-data body. Be mindful of setting two consecutive dashes (for example, –foo_bar_baz–) to mark the end of the boundary within the body of the HTTP request and two additional CRLFs after the boundary delimiters. If you are using Azure Logic Apps, go to the Logic App Code View. Within the HTTP body definition, replace every \n with \r\n. This is the key for successful file upload with multipart/form-data HTTP request using Azure Logic Apps. Upload next chunks of the file To upload the file in multiple chunks follow the steps: Create a PUT request to the method’s /files URI. Add the query parameter uploadType=resumable Add the query parameter uploadToken=[uploadToken] Add the query parameter position=[position] Example - Request to upload next chunks of the file Put v1.0/files ?uploadType=resumable &uploadToken=[uploadToken] &position=[position] Add the chunk’s data to the request body. Create chunks of a maximum of 9MB. It’s recommended to have chunks with the same size, except for the final chunk that completes the upload. Add the top-level HTTP header Content-Type. Set to application/octet-stream Send the request, and process the response. If the upload request is interrupted, or if you receive a 5xx response, send the request again. If the request succeeds, the server responds with 206 Partial Content, along with the upload token. Repeat steps 1 through 7 for each chunk that remains in the file. It’s possible to parallel the upload of the intermediate chunks. The last chunk needs to be sent at the end of the requests, to close the session once that you have received confirmation that the previous chunks have been stored successfully. Example - Upload next chunks of the file. This example shows a request that sends the next bytes of the file, and uses the upload token obtained in the previous step: PUT/mft/v1.0/files ?uploadType=resumable &uploadToken=4927b6ffb51445ee982237ab6e4b3b30 &position=1 HTTP/1.1 Host: api.youserve.nl x-raet-tenant-id: sandbox Authorization: Bearer xxxxxxxxx Content-Type: application/octet-stream And this is the second chunk of the file If the request succeeds, the server responds with 206 Partial Content Example - Successful response of intermediate request HTTP/1.1 206 Complete a resumable upload session There are two ways to complete a resumable upload session: a) Add the query parameter close=true in the last PUT request. b) Send additional Post request without bytes. Complete a resumable upload session in the last PUT request To complete a resumable upload session in the last upload request follow the steps described in section: “Upload next chunks of the file” and Add the query parameter close=true Add the top-level HTTP header: Content-Type. Set to application/octet-stream Example - Put Request to complete a resumable upload session Put https://api.youserve.nl/fileapi/v1.0/files ?uploadType=resumable &uploadToken=[uploadToken] &position=[position] &close=true If the request succeeds, the server responds with 201 created, along with the metadata of the file. Example - Complete a resumable upload session in the last upload request PUT/fileapi/v1.0/files ?uploadType=resumable &uploadToken=4927b6ffb51445ee982237ab6e4b3b30 &position=2 &close=true HTTP/1.1 Host: api.youserve.nl x-raet-tenant-id: sandbox Authorization: Bearer xxxxxxxxx Content-Type: application/octet-stream And this is the last chunk of the file This example shows a request that sends the last bytes of the file, and complete the upload of the file, using the upload token obtained in the previous step: If the request succeeds, the server responds with 201 Created, along with the metadata of the file. Example - Successful response of final request HTTP/1.1 201 Content-Type: application/json { "id": "7ff1b498-169d-4048-8459-78f7bd7905a3", "name": "TestFile.txt", "size": 78, "creationDate": "2020-02-27T11:03:49.2033291Z", "tenantId": "sandbox", "businessType": { "id": 7100, "name": "7100" }, "numChunks": 2 } Complete a resumable upload session sending an additional Post Request To complete a resumable upload session sending an additional Post request without bytes, follow the steps: Create a POST request to the method’s /files URI. Add the query parameter uploadType=resumable Add the query parameter uploadToken=[uploadToken] Do not add the top-level HTTP header: Content-Type. Example - Post Request to complete a resumable upload session Post https://api.youserve.nl/fileapi/v1.0/files ?uploadType=resumable &uploadToken=[uploadToken] If the request succeeds, the server responds with 201 created, along with the metadata of the file. Example - Complete a resumable upload session sending an additional Post request. This example shows a request that sends and additional Post request to complete the upload of the file, using the upload token obtained in the previous step: Post/fileapi/v1.0/files ?uploadType=resumable &uploadToken=4927b6ffb51445ee982237ab6e4b3b30 HTTP/1.1 Host: api.youserve.nl x-raet-tenant-id: sandbox Authorization: Bearer xxxxxxxxx If the request succeeds, the server responds with 201 Created, along with the metadata of the file. Example - Successful response of final request HTTP/1.1 201 Content-Type: application/json { "id": "7ff1b498-169d-4048-8459-78f7bd7905a3", "name": "TestFile.txt", "size": 78, "creationDate": "2020-02-27T11:03:49.2033291Z", "tenantId": "sandbox", "businessType": { "id": 7100, "name": "7100" }, "numChunks": 2 }   File list of uploaded files This endpoint allows you to retrieve a paginated collection of the files that have been uploaded by you. In order to use the list endpoint: Create a Get request to the method’s /files URI and add the query parameter role=publisher Example - List Uploaded Files GET https://api.youserve.nl/fileapi/v1.0/files?role=publisher Optional Parameters Parameter Name Value Description pageIndex integer The number of the page. (Default:0) pageSize integer The maximum number of files to return per page. Acceptable values are 1 to 1000, inclusive. (Default: 20) Example - List Uploaded Files. This example shows how to list the files that have been uploaded by you (role=publisher) GET/fileapi/v1.0/files ?role=publisher &pageSize=10 HTTP/1.1 Host: api.youserve.nl x-raet-tenant-id: sandbox Authorization: Bearer xxxxxxxxx If the request succeeds, the response includes a 200 OK HTTP status code, along with the paginated collection of the files that were uploaded by you. By default, the paginated collection of files will be ordered by date descending. Example - Response of List Uploaded Files HTTP/1.1 200 Content-Type: application/json { "data": [ { "fileId": "4a31f004-aab8-4419-9072-077c35074553", "fileName": "TestFile1.txt", "fileSize": 209715222, "tenantId": "sandbox", "businessType": { "id": 7100, "name": "7100" }, "publisherId": "1b604f7e-d40f-466d-b9b0-ddeb3945df14", "uploadDate": "2021-01-10T21:05:41.937" }, { "fileId": "62777c81-e83f-4888-8202-cf35ea2ca38b", "fileName": "TestFile2.txt", "fileSize": 2048, "tenantId": "sandbox", "businessType": { "id": 7100, "name": "7100" }, "publisherId": "1b604f7e-d40f-466d-b9b0-ddeb3945df14", "uploadDate": "2021-01-10T08:07:41.113" } ], "pageIndex": 0, "pageSize": 20, "count": 2 }     Search for uploaded files To search for a specific set of files, use the query string $filter to filter the files to return.   The format of the query string is: field operator values Where: field specifies the field to search upon. operator specifies the condition for the field. values are the specific values you want to use to filter your search results. Field Description Values uploadDate Upload Date according to DateTime OData format <DateTime> businessType Business Type ID <BusinessTypeId> fileName Name of the file <FileName>   Operator Description gt Great than lt Less than ge Great than or equal le Less than or equal eq Equal ne Not equal and And or Or ( Open Parenthesis ) Close Parenthesis startsWith parameter starts with the following substring (only for fileName) endsWith parameter ends with the following substring (only for fileName) contains parameter contains the following substring (only for fileName) Query string examples What you want to query Query String Files greater than 2020-05-19T08:42:47.400Z uploadDate gt 2020-05-19T08:42:47.400Z Files greater than 2020-05-19T08:42:47.400Z and lesser than 2020-05-19T16:42:47.400Z uploadDate gt 2020-05-19T08:42:47.400Z and uploadDate lt 2020-05-19T16:42:47.400Z Files related to BusinessTypeID 7100 businessType eq 7100 Files related to BusinessTypeID 999998 or 999999 businessType eq 999998 or businessType eq 999999 All Files greater than 2020-05-19T08:42:47.400Z related to BusinessTypeID 7101 uploadDate gt 2020-05-19T08:42:47.400Z and businessType eq 7101 All files with a name that starts with “payroll” startsWith(FileName, 'payroll') All files with a name that ends with “holidays“ endsWith(FileName, 'holidays') All files with a name that contains “test“ contains(fileName, 'test') All files with a name that starts with “payroll“ and a BusinessTypeId 7101 startsWith(FileName, 'payroll') and businessType eq 7101     Sort uploaded files To sort the files in an specific order, use the query string $orderBy   The format of the query string is: field modifier Where: field specifies the key to sort. Valid keys are ‘uploadDate’, ‘businessType’, ‘fileName’. modifier specifies the order of the sorting (‘asc’ and ‘desc’) Example usage: ?$orderBy=uploadDate asc By default, files are sorted by UploadDate desc. Note: The order in which files need to be downloaded may depend on the type of data and the way the receiving system needs to process it. See examples below: Query string examples What you want query Query String Retrieve ‘RST Functie’ files (BT: 101002. Definition of all functions/positions available in Beaufort/YouForce). You would only need the latest file so you can ignore the rest, as each file contains the complete list of functions/positions. $filter=businessType eq 101002 . In this case, the $OrderBy query string is not needed, as files are sorted by UploadDate desc by default. Retrieve employee mutations in Bint Harmony Files (BT: 101100). Based on the default settings that Beaufort/YouForce only exports the mutations instead of the full employee dataSet, it is important that you get all the new files and download them from old to new. $filter=businessType eq 101100&$orderBy=uploadDate asc     File download uploaded files This endpoint allows you to download the files that have been uploaded by you. In order to use this download endpoint: Create a Get request to the method’s /files/[fileId] URI and add the query parameter role=publisher Add the HTTP header Accept=application/octet-stream Example - Download Request GET https://api.youserve.nl/fileapi/v1.0/files/[fileId]?role=publisher Example - Download uploaded file. This example shows how to download a file that was uploaded by you using the Sandbox Tenant GET/fileapi/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696 ?role=publisher HTTP/1.1 Host: api.youserve.nl x-raet-tenant-id: sandbox Authorization: Bearer xxxxxxxxx Accept: application/octet-stream If the request succeeds, the response includes a 200 OK HTTP status code, along with the bytes of the file. Example - Successful response of Download uploaded File HTTP/1.1 200 <root> <company>Visma YouServe</company> <product>File API</product> <content>Sample File</content> </root>   Troubleshooting A few checks for mitigation Setting the right boundary definition for multipart/form-data body. Be mindful of setting two consecutive dashes (for example, –foo_bar_baz–) to mark the end of the boundary within the body of the HTTP request and two additional CRLFs after the boundary delimiters. If you are using Azure Logic Apps, go to the Logic App Code View. Within the HTTP body definition, replace every \n with \r\n. This is the key for successful file upload with multipart/form-data HTTP request using Azure Logic Apps.     ... View more

The File API allows you to download or upload files directly from YouServe, over HTTPS using the tool of your choice.     Introduction Overview Concepts The File API is intended to upload and download files from system to system in a secure way. Files can be uploaded to and downloaded from the YouServe domain. Files can be uploaded or downloaded with authorized apps, specified for a specified tenant, for specified business type(s). A publisher app to upload files, a subscriber app to download files:     Explanation of  concepts  Concept Description File API Public endpoint to upload/list/download the files. In the request to File API, client id, business type id and tenant id are being identified. Once the files are uploaded to File API by a publisher application, the authorized subscriber application can list, download and delete the files. Business Type/File type The files which are related to the same “business” are functionally grouped in File types called “Business types”. File types are represented by an integer called “Business type id”. Client Application Client Applications are the users of the system. They are identified by a client Id. Client Applications are also authorized to tenantId(s). Client application needs to obtain a authentication token by using credentials (client id and client secret).The token includes client id, tenant id and the scopes of the application. Client Applications could be authorized either as publisher or subscriber of a business type. Publisher Publisher is a Client Application that can upload files of authorized business types and authorized tenants. The uploaded files can also be listed/downloaded. Subscriber Subscriber is a Client Application that can list/download/delete the files of authorized business types and authorized tenants. Tenant HR Core Client. Tenants are represented by tenant ids.   Encryption & Communication File API is running on the Azure Cloud and has a microservice architecture to provide the best availability to the customers. The communication between microservices which form File API system, is restricted by an internal token. Https is the main communication protocol for external and internal communication. Database communication protocol is TLS 1.2. File content is stored in Azure Storage and automatically encrypted when it is persisted to the cloud. Similarly all the databases are encrypted by Azure database encryption.   Authentication We follow current industry standards and best practices. Authentication/authorization is not an exception. As part of the Identity and Access Management Strategy for system-to-system integrations, the File API is based on OAuth 2.0 and the authorization grant Client Credentials. Every API consumer system will be provisioned in our API Gateway as a Client Application (App). Client ID and Client Secret will be provided to be used by Apps as credentials. Thus, Apps will be able then to authenticate and get an access token (JWT) within the response payload. Subsequent requests authorization will be based on that access token previously retrieved. Tenant Authorization Client Applications (apps) need to be authorized to the corresponding Tenant (HR Core Client) in order to consume the API. By default, the applications are authorized to TenantId: sandbox. File Type Authorization Client applications (apps) need to be authorized as publisher or subscriber of business types By default, sandbox apps are authorized to the Sandbox File Types. Supported File Types The File API has been designed to support a specific set of use cases. This may be extended over time, based on customer feedback. See the supported File Types. Retention Period The files will be physically deleted from Storage automatically after the retention period expires (1 month). The metadata of the files (FileName, tenantId , BusinessTypeId, etc) is deleted after 6 months. Curl Example Here is an example of downloading a file using curl, available on most operating systems: curl.exe https://api.youserve.nl/fileapi/v1.0/files/%fileid%?role=subscriber ^ --header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." ^ --header "x-raet-tenant-id: 1234567" ^ --header "Accept: application/octet-stream" ^ --output @C:/Youserve/somefile.xml See complete examples for curl (Batch) and .Net in Github.   Getting started Create Sandbox Application 1. Create account in the YouServe developer portal YouServe developer portal   2. Create new File API Sandbox App       3. Retrieve credentials (Api Key, Secret key)       Get Access Token 1. Send request to Authentication API The Authentication API is used to obtain the required access token. The request must include the content type header and the HTTP body must include the required Client Credentials. curl -X POST 'https://api.youserve.nl/authentication/token' -H 'Cache-Control: no-cache' -H 'Content-Type: application/x-www-form-urlencoded' -d 'client_secret=xxxxxxx&client_id=xxxxxxxx&grant_type=client_credentials' Below, a response example containing the access token and the expiration time which is 2 hours. After that time Apps need to re-authenticate to get a new access token. { 'access_token':'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...', 'token_type': 'BearerToken', 'expires_in': '7200', } Send request to File API Endpoint including the access token App must use the Authorization header containing the access token. The API always operates within the scope of one HR Core client, also called tenant. An API call cannot retrieve data from multiple tenants. By default, sandbox apps are authorized to the Sandbox File Types: Business Type Id Name Authorization 7100 File API Sandbox Uploads Publisher 7101 File API Sandbox Downloads Subscriber Below, a request example for listing sandbox files: curl -X GET 'https://api.youserve.nl/fileapi/v1.0/files/%fileid%?role=subscriber' -H 'Cache-Control: no-cache' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' -H 'x-raet-tenant-Id: sandbox' Authentication Error Response The error payload shown below, describes the 401 error response Apps will receive in case of any authentication error. { 'message': 'Authentication Error', 'correlationId': 'rrt-0d027480041e2a148-a-de-7885-572449-1', 'issuedAt': '2018-03-27T07:44:25.554Z', 'errorCode': 'unauthorized', 'statusCode': 401 } Miss use reasons for having authentication errors are: Wrong credentials Expired credentials Unauthorized access tokens Expired access tokens For more detailed information please refer to the request headers & responses section File API Endpoints Once you have a valid access token you can perform below actions as publisher of the file types: Upload List uploaded files Download uploaded files As subscriber of the file types you can perform below actions: List Available Files Download Delete In case you have any question or doubt during the integration, you can reach us through the Visma Developer Community in Slack. See our Support page for more information.   Request headers and responses See below the request headers and response codes of File API.   Request headers Header Name Description Content-Type The content type of the resource in case the request has content in the body. Example: Content-Type:multipart/related;boundary=foo_bar_baz Authorization The information required for authentication Accept The Accept request-header can be used to specify the media types which are acceptable for the response. Example: Accept:application/octet-stream Response codes Type Responses Situation Success Codes 200 OK Synchronous read, update, and delete operations 201 Created Synchronous create requests   202 Accepted A-synchronous operations   204 No Content Referring to non-existing entity (e.g. after delete)   Redirection Codes 304 Not Modified Resource has not been modified. 308 Permanent redirect Resource has permanently moved.   Invalid Request Errors 400 Bad request Bad Request (e.g. validation errors) 401 Unauthorized Not Authorized: Missing or invalid access token Reasons for having authentication errors are:Wrong credentials, Expired credentials, Unauthorized access tokens, Expired access tokens 403 Forbidden Not Authorized: Authenticated, but user has no access to the API   404 Not Found Invalid URL: Item does not exist (anymore). The canonical identifier (collection/{canonical id}) cannot be found. Not Authorized: Authenticated, access to api, but user has no access to to the resource (data authorization). From a security standpoint we don’t expose the reason why the object could not be found because an attacker can use this to figure out the internals of our system.   409 Conflict Concurrency problem: Record changed by another user   Server Errors 500 Internal server error Server Error (e.g. database failure, event could not be send) 503 Service unavailable Server Error (resource temporary not available)       Usage Limits We apply usage limits to ensure the availability of our services to all parties interacting with YouServe. These usage limits depend on your subscription.   Policy The following policies are determined per registered application: Quota Weekly Daily Continous API calls 2 hours per day. 1000 API calls within the time window. 7 days per month 2 hours per day. 1000 API calls within the time window. 40 times per month 6000 API calls per day, allowing to retrieve changes every 15 seconds Authentication calls 7 successful authentication calls per month 40 successful authentication calls per month 400 authentication calls per month Concurrent rate-limiting (API calls in parallel) 1 1 3 Spike arrest policy (max number of API calls per minute) 100 calls per minute 100 calls per minute 100 calls per minute 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.   ... View more

Update March 11 2023, 14:45PM   The technical maintenance has already ended. The domain API's will supply changes as normal from HR Core Business.   Original message    Due to technical maintenance on HR Core Business, although the domain APIs will be available, it will not supply any changes from Friday 10 March 2023 6:00 PM to Sunday 12 March 2023 6:00 PM. If the work is completed earlier, we will let you know during the weekend of 10 to 12 March 2023. We apologize for the inconvenience.     ... View more

In September 2020, we added a new version of the Employees endpoint to the MLM API. For details on v1 versus v2, please read this article.   Per the first of July 2023, we are moving the old version 1.0 from deprecated to retired. This means we will stop the availability of the endpoint.    If you still use this endpoint, we urge you to start using the Employees v2 version.   Q1: How do I know which version I use? A1: If you don't use header variable Accept-version with version 2.0, you are using the v1.0 This indicates usage of v2.0   Q2: What are the differences between v1.0 en v2.0? A2: All fields available in v1.0 are available on v2.0, except for 1 field. This concerns the personId field. The personId in v1.0 is the id field in v2.0. See below for an overview:   Field v1.0 v2.0 id mutkey of employee personNumber (elementnr: 10519680) personId personNumber (elementnr: 10519680) not available   The mutkey of the employee is not available in v2.0. To identify employees, the personId and personcode can be used   ... View more