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

  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 Payroll Batch Input Imports Name Payroll Batch Input Imports 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 mutaties". To configure this type, ask your (payroll) consultant or account manager.     Payroll EMA Imports Name Payroll EMA Imports Business type id 113002 Type Upload to YouServe Owner HR Core Payroll Business Info File Pattern: <TENANTID>_<COMPANYKEYCOD>_<OPTIONAL>.<EXTENSION>   Description of this type can be found in the online help of HR Core Payroll Business. Search for the keywords: "externe mutaties". To configure this type, ask your (payroll) consultant or account manager.     Journal entries / Journaalposten Export Name Journal entries / 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.     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 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

Status: Solved   Scope of issue: All domain APIs (MLM, IAM, WFM, Recruiting, learning, Payroll, API for BI systems)   Description of situation: Starting around 13th of Januray 2023 11:15, we have a production issue in our Service Gateway. This causes that the connection for all domain APIs is down. The token to connect to the domain APIs cannot be created. Also it is not possible to login the developer portal of YouServe (http://developers.youserve.nl). We are analysing the issue with highest priority. We will keep you updated about the situation.   Update (13-1-2023 6:30pm): Around 6pm on 13th of January 2023, a solution was deployed to production. After deployment, the token to access the domain APIs was created again. Customers can retrieve data again in the endpoints of the domain APIs using the existing processes.   At the moment, the Visma YouServe developer portal (http://developers.youserve.nl) is not fully accessible yet.  Users cannot login and options on APIs like "status page", "API library" (overview) and "Your Apps" are not available yet. We are working on a solution to have all the functionalities available again.   Update (18-1-2023 8:30am): Visma YouServe developer portal is not fully accessible. Analysis and development of solution is ongoing. We expect the portal to be available again by the end of the week.   Update (20-1-2023 10:00am): Visma YouServe developer portal is fully accessible. Users can login, "Your Apps" and "API library" are available again. Only "API status" page is not yet available. We will continue to work on this last page, general disturbance message will be closed however.   First occurrence of issue: 13-1-2023, 11:15am   Impact:  No connection can be setup to Domain APIs. Customers cannot receive data updates from HR Core Business using the domain APIs.   Issue solved: 13-1-2023, 6pm   ... View more

The File API allows you to download or upload files directly from Youforce, over HTTPS using the tool of your choice.     Introduction Overview 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 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.   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.raet.com/mft/v1.0/files/%fileid%?role=subscriber ^ --header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." ^ --header "x-raet-tenant-id: 1234567" ^ --header "Accept: application/octet-stream" ^ --output @C:/Youforce/somefile.xml See complete examples for curl (Batch) and .Net in Github.   Getting started Create Sandbox Application 1. Create account in the Youforce developer portal The File API is provided and supported by Visma Raet. To use the File API, the Visma Raet Developer Portal is used. Youforce 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.raet.com/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.raet.com/requests/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 Youforce. 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.   Publishers 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.raet.com/mft/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.raet.com 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.raet.com/mft/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.raet.com 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.raet.com 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.raet.com/mft/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/mft/v1.0/files ?uploadType=resumable &uploadToken=4927b6ffb51445ee982237ab6e4b3b30 &position=2 &close=true HTTP/1.1 Host: api.raet.com 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.raet.com/mft/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/mft/v1.0/files ?uploadType=resumable &uploadToken=4927b6ffb51445ee982237ab6e4b3b30 HTTP/1.1 Host: api.raet.com 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.raet.com/mft/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/mft/v1.0/files ?role=publisher &pageSize=10 HTTP/1.1 Host: api.raet.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 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.raet.com/mft/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/mft/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696 ?role=publisher HTTP/1.1 Host: api.raet.com 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 Raet</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.       Subscribers 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.raet.com/mft/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/mft/v1.0/files ?role=subscriber &pageSize=20 &$filter=businessType eq 8000 &$orderBy=uploadDate desc HTTP/1.1 Host: api.raet.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.raet.com/mft/v1.0/files/[fileId]?role=subscriber Example - Download Available File. This example shows how to download a file that was delivered to you GET/mft/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696 ?role=subscriber HTTP/1.1 Host: api.raet.com 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 Raet</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/mft/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696 ?role=subscriber HTTP/1.1 Host: api.raet.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 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/mft/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696 ?role=subscriber HTTP/1.1 Host: api.raet.com 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 Raet</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/mft/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696 ?role=subscriber HTTP/1.1 Host: api.raet.com 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.raet.com/mft/v1.0/files/d92ffb21-7938-488b-a405-bcbc9e0a9696 ?role=subscriber HTTP/1.1 Host: api.raet.com 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         File types Sandbox file types Owner Type Business TypeId Business Type Name File Transfer Sandbox 7101 File API Sandbox Downloads File Transfer Sandbox 7100 File API Sandbox Uploads     HR Core/Payroll Business file types Owner Type Business Type Id Business Type Name File Patterns Remarks HRCB Import 113000 Payroll Netive Imports <TENANTID>_<DATE&TIME>.txt   HRCB Import 113001 Payroll Batch Input Imports <TENANTID>_<OPTIONAL>.<EXTENSION> See Batch input imports documentation and note below (*) HRCB Import 113002 Payroll EMA Imports <TENANTID>_<COMPANYKEYCOD>_<OPTIONAL>.<EXTENSION> See note below **) HRCB Export 113003 Journaalposten Export RPD.<TENANTID>.*.*   * Note Batch Input Imports: The contents of the optional block are not used by the import. Please make sure there is an underscore before it so that the tenantId can be parsed correctly. The optional block may be used to make sure the filename is unique and the file is identifiable: The date and time are recommended for this. The extension could be txt or dat ** Note EMA Imports: The contents of the optional block are not used by the import. Please make sure there is an underscore before it so that the CompanyKeyCod can be parsed correctly. The optional block may be used to make sure the filename is unique and the file is identifiable: The date and time are recommended for this. The extension is free to use, this could be txt or csv. Here you can see the description of the External mutations Advanced as it is in the Online help of HR Core Business. This document explains how to create a file for testing in Excel.         Betaalmanager file types RBM Exports - Business Owner Type Business TypeId Business Type Name File Patterns RBM Export 134000 RBM Business Downloads *_SEPA.csv RBM Export 134001 RBM Business Payment Files *_SEPA.xml, *_SEPA.zip Note: See release notes to configure File API exports in Betaalmanager       External payslips file types External Payslips Import Owner Type Business Type Id Business Type Name File Patterns Younifier Import 105000 External Payslips Import *.zip     Robotics file types Robotics Exports Owner Type Business TypeId Business Type Name File Patterns Robotics Export 137000 Robotics Youserve Exports *.*     Loonaangifte file types Loonaangifte Business Exports Owner Type Business TypeId Business Type Name File Patterns Loonaangifte Export 102000 Loonaangifte Business Export *.zip       Personneldossier file types Personneldossier Exports Owner Type Business TypeId Business Type Name File Patterns Personneldossier Export 107001 Personeels dossier Exports *.zip Personneldossier Imports Owner Type Business TypeId Business Type Name File Patterns Remarks Personneldossier Import 107000 Personeels dossier Imports *.zip See Personnel File imports documentation       Salarisdossier file types Salarisdossier Exports - Business Owner Type Business TypeId Business Type Name File Patterns Remarks Salarisdossier Export 136000 Salarisdossier Business Exports ExportDossier*.zip Payslips and Annual statement files are included       Examples to integrate .Net with File API SDK You can integrate with our File API Net SDKs. The SDK to connect to the File API is available at nuget. Documentation about how to use the SDK and our examples is at GitHub.   PowerShell You can integrate with PowerShell scripts. Documentation about how to use PowerShell and our examples is at GitHub.     Postman The ZIP Postman Collections that you can download here include the following information: Postman collection Postman environment Sample set of files Download Zip Postman Collection for Youforce Developer Portal Apps (It will be deprecated)         Release notes Contents Changelog 2022 Changelog 2022 Date Changes 2022-07-02 Database columns have been converted to improve database performance. During this maintenance activity the performance of publisher endpoints was degraded and subscriber endpoints had to be disabled. See status.visma.com for additional details about this maintenance activity 2022-06-01 New payroll file types have been defined per core. See section Payroll File - File Types 2022-05-31 New RBM file types have been defined per core. See section RBM File Types 2022-05-27 - Added the possibility of filtering and sorting for publishers. See section Search uploaded files and section Sort uploaded files - Added 403 error message when the request contains a filter by a non authorized business type 2022-02-15 Updated FileAPI.json file, replacing “v1” by “v1.0” to support integrations using Azure API management (APIM). No action is required from your side, as File API Endpoints have not changed 2022-01-21 Created download Endpoint for publishers. See section Download uploaded files     Policies API Statuses Definition of our 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. You can also find this information in the Service Level Agreement   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 Raet 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 Raet 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 Raet aims to have a maximum of one major release per year. Each major release will be supported for at least 24 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. Raet 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. Developers & Visma Community All recipients & File API contact persons 1st notification 6 months prior to decommissioning Developers & Visma Community File API contact persons 2nd notification 3 months prior to decommissioning Developers & Visma Community File API contact persons 3rd notification 1 months prior to decommissioning Developers & Visma Community File API contact persons       Support In case you have any question or doubt during the integration, you can reach us through the Visma Developer Community in Slack. Developers that use the File API or other Youforce APIs can use this community to talk with Visma developers that design and implement these APIs Visma consultant that help to connect with customer environments Other File API consumers You can join here. Anyone can join! Each Youforce API has it’s own channel starting with #youforce. The File API channel is #youforce-file-api.     Swagger API reference can be found here.     ... View more

We follow current industry standards and best practices. Authentication/authorization is no exception. As part of the Identity and Access Management Strategy for system-to-system integrations, our APIs are 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). API key (client_id) and Secret key (client_secret) will be provided to be used by Apps as credentials. Apps will be able to authenticate and get an access token (JWT) within the response payload. Subsequent request authorization will be based on that access token previously retrieved.     A detailed explanation is available in our knowledge base.   Additional security level: Secured OAuth2 flow with client private key Demands for security measures are always increasing. Upon the existing authentication, we have added an extra security level: Secured OAuth2 flow with client private key. With this addition, the identification with API key (client_id) and Secret key (client_secret) is replaced by an API Key (client_id) + client_assertion (private key) which will be verified with a stored public key. The access token (JWT) will be delivered and can be used to retrieve data.      A detailed technical explanation of how to use the increased security level is available in our knowledge base. If you want to start using the increased security level, please contact your account manager or Service Delivery Manager.     ... View more

Status: Solved   Scope of issue: All doman APIs (MLM, IAM, WFM, Recruiting, learning, Payroll)   Description of situation: No response on domain APIs.   First occurrence of issue: 12-7-2022, 2:45am   Impact:  The issue is fixed. No data lost, data updates can be delayed.   Issue solved: 12-7-2022, 9:45am ... View more

  22-03-2023: property employmentIndicator added to Employments endpoint Persons endpoint - The property employmentIndicator is added to the Employments endpoint.  Endpoint documentation is updated.   23-01-2023: property Identity added to Persons endpoint Persons endpoint - The property Identity is added to the Persons endpoint.  Endpoint documentation is updated.   3-10-2022: new endpoint LeaveBalances We have added 1 more endpoint to the WFM API: LeaveBalances. This new endpoint is available for all WFM API consumers. The LeaveBalances endpoint delivers information about  leave entitlement and the leave taken. Learn more about this endpoint in our knowledge base.   23-8-2022: change fields PersonId/Personcode The properties PersonId and Personcode did not refer to the same source in HR Core Business throughout the WFM API. Sometimes the property PersonId refered to the UPI, sometimes to the Personcode. Same for the property Personcode. To have a logical and more intuitive explanation of the properies, we have synchronized the mapping throughout the WFM API.   The PersonId and Personcode is synchronized for all endpoint in WFM API: PersonId - refers to the UPI (NL: Uniek Persoonlijk Id) in HR Core Business PersonCode  - refers to the Person code (NL: Persoonscode) in HR Core Business This change has no impact for consumers of the WFM API. When the Person layer is enabled in HR Core Business (requirement for normal usage of WFM API), these values are the same. Therefore, switching the mapping in the WFM API has no impact for WFM API consumers.      19-07-2022: change of description of leaveBalancesPayroll endpoint LeaveBalancesPayroll endpoint - The HR Core Business example of Id property has changed.   Old text: id - Combined field of: [PersonId] +  [Payroll year] + [Payroll period] ... New: id - Combined field of: [EmployeeId] +  [Payroll year] + [Payroll period] ... The description of the user endpoint : WFM LeaveBalancesPayroll endpoint.   13-07-2022: Leaves endpoint Three more endpoints are added to the WFM API: Leaves, LeaveTypes, LeaveReasons. Learn more about these endpoints in our knowledge base.     13-05-2022: managerPersonCode removed from endpoint OrganizationUnits The property managerPersonCode is removed from endpoint OrganizationUnits. Although described in the documentation and swagger, the property was never supported and has the same value as managerPersonId. Documentation and swagger page are adjusted. To Identify the manager of a organizationalUnit, the property managerPersonId can be used. Description of endpoint: OrganizationUnits     ... View more

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

Status: Solved   Scope of issue: MLM API and WFM API, Endpoint: Sickleaves   Description of situation: When a sick leave dossier contain multiple partial recoveries, then the partial recoveries of the same percentages are undoubled and reduced to only the latest partial recovery. This also includes the first sick leave time slice (100% sick).    Example:  Sick leave in HR Core Business: 01-03-2022 100% sick 10-03-2022 75% sick 15-03-2022 50% sick 20-03-2022 100% sick 25-03-2022 50% sick 30-03-2022 25% sick   Results in the output of SickLeaves endpoint, PartialRecoveries  property during disturbance: 10-03-2022 75% sick 20-03-2022 100% sick 25-03-2022 50% sick 30-03-2022 25% sick   First occurrence of issue: 29-3-2022, 12:00   Impact:  Not all partial recoveries are delivered in the PartialRecoveries property of the output in the MLM and WFM API, endpoint SickLeaves from 29-3-2022 (12pm) up till 6-4-2022 (10am). This only concerns sick leaves with multiple partial recoveries of same percentage. It only concerns the property PartialRecoveries. To repair data output in the SickLeaves endpoint, we will reload all sick leave data from HRCore to the API platform. This repair takes place on the 6th of April 2022.   Issue solved: 6-4-2022, 10:00     ... View more

Extra fields endpoints Employees & Contracts We’ve added two fields "noRisk" & "endDateNoRisk" to the endpoint /contracts & /employees (V1 / V2) related to the data of HR coresystem HRCB (r1). In this HR core system users are able to manage the following WIA / no-risk related elements :   The field ‘No Risk polis van toepassing' is a dropdown with the options Ja/Nee. The field 'Einddatum no risk periode’ is a date field. For sharing this relevant information to external MLM systems / UWV, we’ve added two extra fields in the /contracts & /employees endpoints of the MLM API: noRisk (boolean field) > mapped to ‘No Risk polis van toepassing'. endDateNoRisk (date field) > mapped to ‘Einddatum no risk periode'. Latest version endpoint /contracts : (see row 25 & 26) [ { "validFrom": "2021-06-10T06:24:53.362Z", "validUntil": "2021-06-10T06:24:53.362Z", "extensions": [ { "key": "string", "value": "string" } ], "id": "string", "isDeleted": true, "employeeCode": "string", "personId": "string", "contractCode": "string", "originalHireDate": "2021-06-10T06:24:53.362Z", "dischargeDate": "2021-06-10T06:24:53.362Z", "hireDate": "2021-06-10T06:24:53.362Z", "company": "string", "employmentType": "string", "contractType": "string", "jobProfile": "string", "organizationUnit": "string", "fullTimeWorkingAmount": 0, "noRisk": true, "endDateNoRisk": "2021-06-10T06:24:53.362Z", "phoneNumbers": [ { "type": "string", "number": "string" } ], "emailAddresses": [ { "type": "string", "address": "string" } ], "workingAmount": { "amountOfWork": 0, "unitOfWork": "string", "periodOfWork": "string" } } ]     Latest version endpoint /employees : (see row 78 & 79) [ { "validFrom": "2021-06-10T06:25:58.121Z", "validUntil": "2021-06-10T06:25:58.121Z", "extensions": [ { "key": "string", "value": "string" } ], "id": "string", "personCode": "string", "isDeleted": true, "initials": "string", "firstNames": "string", "knownAs": "string", "lastNameAtBirth": "string", "lastNameAtBirthPrefix": "string", "lastName": "string", "lastNamePrefix": "string", "nameAssembleOrder": "string", "partnerName": "string", "partnerNamePrefix": "string", "titlePrefix": "string", "titleSuffix": "string", "gender": "string", "birthDate": "2021-06-10T06:25:58.121Z", "deceasedDate": "2021-06-10T06:25:58.121Z", "nationalIdentificationNumber": "string", "userUID": "string", "phoneNumbers": [ { "type": "string", "number": "string" } ], "emailAddresses": [ { "type": "string", "address": "string" } ], "addresses": [ { "type": "string", "streetName": "string", "houseNumber": "string", "houseNumberAddition": "string", "postalCode": "string", "city": "string", "country": "string" } ], "contracts": [ { "validFrom": "2021-06-10T06:25:58.121Z", "validUntil": "2021-06-10T06:25:58.121Z", "extensions": [ { "key": "string", "value": "string" } ], "id": "string", "isDeleted": true, "employeeCode": "string", "personId": "string", "contractCode": "string", "originalHireDate": "2021-06-10T06:25:58.121Z", "dischargeDate": "2021-06-10T06:25:58.121Z", "hireDate": "2021-06-10T06:25:58.121Z", "company": "string", "employmentType": "string", "contractType": "string", "jobProfile": "string", "organizationUnit": "string", "fullTimeWorkingAmount": 0, "noRisk": true, "endDateNoRisk": "2021-06-10T06:25:58.121Z", "phoneNumbers": [ { "type": "string", "number": "string" } ], "emailAddresses": [ { "type": "string", "address": "string" } ], "workingAmount": { "amountOfWork": 0, "unitOfWork": "string", "periodOfWork": "string" } } ] } ]   By using the fields ‘No Risk polis van toepassing' & 'Einddatum no risk periode’ in the above screen of HRCB the ‘sickleave coordinators' of our customers can manage all fields for administrative purposes. Only the red alligned elements are exposed to the MLM API for external sharing reasons. ... View more

Extra fields endpoint Sickleaves We’ve added two fields "internalFollowUp" & "additionalNote" to the endpoint /sickleaves. HR coresystem HRCB (r1) added these two elements in the front-end application, see below :      By using the fields Actielijst & Korte notitie on the sickleave screen of HRCB the ‘sickleave coordinators' of our customers can select the necessary follow-up activities in the core system.The follow-up values are flexible configurable per client / tenant via Waardelijsten / Valuelists. The field Korte notitie can process up to 100 characters. Because of this we’ve added two extra fields in the /sickleaves endpoint of the MLM API: internalFollowUp (string) > mapped to ‘Actielijst’. Provides a code. Via /valuelists the corresponding values can be retrieved. additionalNote (string) > mapped to ‘Korte notitie’. Latest version endpoint /sickleaves :   [ { "id": "string", "isDeleted": true, "personId": "string", "contractId": "string", "reportingDate": "2021-05-11T09:25:42.632Z", "startDate": "2021-05-11T09:25:42.632Z", "hoursWorkedFirstDay": 0, "sicknessType": "string", "absenceReason": "string", "recoveryDate": "2021-05-11T09:25:42.632Z", "expectedRecoveryDate": "2021-05-11T09:25:42.632Z", "recourse": true, "ongoingSickness": true, "safetynet": "string", "dateWVP": "2021-05-11T09:25:42.632Z", "urgentCheckRequired": true, "expectedFinalResult": "string", "finalResult": "string", "internalFollowUp": "string", "additionalNote": "string", "partialRecoveries": [ { "illnessPercentage": 0, "startDate": "2021-05-11T09:25:42.632Z" } ], "nursingAddresses": [ { "startDate": "2021-05-11T09:25:42.632Z", "endDate": "2021-05-11T09:25:42.632Z", "nameCareAddress": "string", "streetName": "string", "number": "string", "numberAdditional": "string", "postcode": "string", "city": "string", "country": "string", "phoneNumber": "string", "faxNumber": "string", "emailAddress": "string", "region": "string", "locationDesignation": "string" } ], "therapeuticPeriods": [ { "startDate": "2021-05-11T09:25:42.632Z", "endDate": "2021-05-11T09:25:42.632Z", "workingAmount": { "amountOfWork": 0, "unitOfWork": "string", "periodOfWork": "string" }, "workingPercentage": 0 } ], "extensions": [ { "key": "string", "value": "string" } ] } ]     To use these extra elements, a full load in the API is needed! ... View more

Extra field endpoint RoleAssignments For the client in our core system HR Core Business there’s a possibility to mark the level of authorisation of a specific Role Assignment. Some roles within an organisation might have more permissions to see or manage processes. In HR Core Business users can manage this via the field ‘Incl. onderliggende OE’s' :     Since 25-Mar '21 the MLM API will also expose this property in the output results of the RoleAssignments endpoint. The name is "includingChildOrgUnits" and will expose the values true / false. The endpoint will look like : [ { "id": "string", "shortName": "string", "fullName": "string", "organizationUnitId": "string", "personId": "string", "employeeId": "string", "includingChildOrgUnits": true, "isDeleted": true, "startDate": "2021-03-22T16:41:38.887Z", "endDate": "2021-03-22T16:41:38.887Z", "extensions": [ { "key": "string", "value": "string" } ] } ]       ... View more

Release field “fullTimeWorkingAmount” In January we’ve improved the field “fullTimeWorkingAmount”, which indicates the full-time hours per period within a specific company. For example 40 or 36 hours per week. This field is now finally released to the PROD environments of the MLM API. In December 2020 this field was already correctly shown in the endpoint: Endpoint /companies [ { "validFrom": "2021-03-22T16:33:20.583Z", "validUntil": "2021-03-22T16:33:20.583Z", "extensions": [ { "key": "string", "value": "string" } ], "id": "string", "code": "string", "name": "string", "totalWorkAmount": "string", "establishmentCountry": "string", "isDeleted": true, "address": { "street": "string", "houseNumber": "string", "houseNumberAddition": "string", "postalCode": "string", "city": "string", "country": "string" }, "mailingAddress": { "boxNumber": "string", "postalCode": "string", "cityTown": "string" } } ]     In January 2021 we’ve corrected the position in the different body responses of other endpoints. Until Dec-2020 the field “fullTimeWorkingAmount” was part of the Person data details. However, the values of this specific field belong to contracts/employments. That’s why we’ve added the field to the endpoints: Endpoint /contracts [ { "validFrom": "2021-03-22T16:34:23.131Z", "validUntil": "2021-03-22T16:34:23.131Z", "extensions": [ { "key": "string", "value": "string" } ], "id": "string", "isDeleted": true, "employeeCode": "string", "personId": "string", "contractCode": "string", "originalHireDate": "2021-03-22T16:34:23.131Z", "dischargeDate": "2021-03-22T16:34:23.131Z", "hireDate": "2021-03-22T16:34:23.131Z", "company": "string", "employmentType": "string", "contractType": "string", "jobProfile": "string", "organizationUnit": "string", "fullTimeWorkingAmount": 0, "phoneNumbers": [ { "type": "string", "number": "string" } ], "emailAddresses": [ { "type": "string", "address": "string" } ], "workingAmount": { "amountOfWork": 0, "unitOfWork": "string", "periodOfWork": "string" } } ] Endpoint /employees [ { "validFrom": "2021-03-22T16:36:27.514Z", "validUntil": "2021-03-22T16:36:27.514Z", "extensions": [ { "key": "string", "value": "string" } ], "id": "string", "personCode": "string", "isDeleted": true, "initials": "string", "firstNames": "string", "knownAs": "string", "lastNameAtBirth": "string", "lastNameAtBirthPrefix": "string", "lastName": "string", "lastNamePrefix": "string", "nameAssembleOrder": "string", "partnerName": "string", "partnerNamePrefix": "string", "titlePrefix": "string", "titleSuffix": "string", "gender": "string", "birthDate": "2021-03-22T16:36:27.514Z", "deceasedDate": "2021-03-22T16:36:27.514Z", "nationalIdentificationNumber": "string", "userUID": "string", "phoneNumbers": [ { "type": "string", "number": "string" } ], "emailAddresses": [ { "type": "string", "address": "string" } ], "addresses": [ { "type": "string", "streetName": "string", "houseNumber": "string", "houseNumberAddition": "string", "postalCode": "string", "city": "string", "country": "string" } ], "contracts": [ { "validFrom": "2021-03-22T16:36:27.514Z", "validUntil": "2021-03-22T16:36:27.514Z", "extensions": [ { "key": "string", "value": "string" } ], "id": "string", "isDeleted": true, "employeeCode": "string", "personId": "string", "contractCode": "string", "originalHireDate": "2021-03-22T16:36:27.514Z", "dischargeDate": "2021-03-22T16:36:27.514Z", "hireDate": "2021-03-22T16:36:27.514Z", "company": "string", "employmentType": "string", "contractType": "string", "jobProfile": "string", "organizationUnit": "string", "fullTimeWorkingAmount": 0, "phoneNumbers": [ { "type": "string", "number": "string" } ], "emailAddresses": [ { "type": "string", "address": "string" } ], "workingAmount": { "amountOfWork": 0, "unitOfWork": "string", "periodOfWork": "string" } } ] } ]     ... View more

  Field “fullTimeWorkingAmount” We’ve improved the field “fullTimeWorkingAmount”, which indicates the full-time hours per period within a specific company. For example 40 or 36 hours per week. This field was already correctly shown in the endpoint: Endpoint /companies [ { "validFrom": "2021-01-12T19:49:43.484Z", "validUntil": "2021-01-12T19:49:43.484Z", "extensions": [ { "key": "string", "value": "string" } ], "id": "string", "code": "string", "name": "string", "totalWorkAmount": "40", "establishmentCountry": "string", "isDeleted": true, "address": { "street": "string", "houseNumber": "string", "houseNumberAddition": "string", "postalCode": "string", "city": "string", "country": "string" }, "mailingAddress": { "boxNumber": "string", "postalCode": "string", "cityTown": "string" } } ] We’ve corrected the position in the different body responses of other endpoints. Until Dec-2020 the field “fullTimeWorkingAmount” was part of the Person data details. However, the values of this specific field belong to contracts/employments. So, that’s why we’ve added the field to the endpoints: Endpoint /contracts { "validFrom": "2021-01-12T19:51:10.147Z", "validUntil": "2021-01-12T19:51:10.147Z", "extensions": [ { "key": "string", "value": "string" } ], "id": "string", "isDeleted": true, "employeeCode": "string", "personId": "string", "contractCode": "string", "originalHireDate": "2021-01-12T19:51:10.147Z", "dischargeDate": "2021-01-12T19:51:10.147Z", "hireDate": "2021-01-12T19:51:10.147Z", "company": "string", "employmentType": "string", "contractType": "string", "jobProfile": "string", "organizationUnit": "string", "fullTimeWorkingAmount": 0, "phoneNumbers": [ { "type": "string", "number": "string" } ], "emailAddresses": [ { "type": "string", "address": "string" } ], "workingAmount": { "amountOfWork": 0, "unitOfWork": "string", "periodOfWork": "string" } } Endpoint /employees { "validFrom": "2021-01-12T19:52:29.217Z", "validUntil": "2021-01-12T19:52:29.217Z", "extensions": [ { "key": "string", "value": "string" } ], "id": "string", "personCode": "string", "isDeleted": true, "initials": "string", "firstNames": "string", "knownAs": "string", "lastNameAtBirth": "string", "lastNameAtBirthPrefix": "string", "lastName": "string", "lastNamePrefix": "string", "nameAssembleOrder": "string", "partnerName": "string", "partnerNamePrefix": "string", "titlePrefix": "string", "titleSuffix": "string", "gender": "string", "birthDate": "2021-01-12T19:52:29.217Z", "deceasedDate": "2021-01-12T19:52:29.217Z", "nationalIdentificationNumber": "string", "userUID": "string", "phoneNumbers": [ { "type": "string", "number": "string" } ], "emailAddresses": [ { "type": "string", "address": "string" } ], "addresses": [ { "type": "string", "streetName": "string", "houseNumber": "string", "houseNumberAddition": "string", "postalCode": "string", "city": "string", "country": "string" } ], "contracts": [ { "validFrom": "2021-01-12T19:52:29.217Z", "validUntil": "2021-01-12T19:52:29.217Z", "extensions": [ { "key": "string", "value": "string" } ], "id": "string", "isDeleted": true, "employeeCode": "string", "personId": "string", "contractCode": "string", "originalHireDate": "2021-01-12T19:52:29.217Z", "dischargeDate": "2021-01-12T19:52:29.217Z", "hireDate": "2021-01-12T19:52:29.217Z", "company": "string", "employmentType": "string", "contractType": "string", "jobProfile": "string", "organizationUnit": "string", "fullTimeWorkingAmount": 0, "phoneNumbers": [ { "type": "string", "number": "string" } ], "emailAddresses": [ { "type": "string", "address": "string" } ], "workingAmount": { "amountOfWork": 0, "unitOfWork": "string", "periodOfWork": "string" } } ] } System HR Core Business The values related to these HRCB clients were “0” until December 2020. In January 2021 we’ve improved the extraction of these values. System HR Core Online (BO4) The values related to these BO4 clients were empty until December 2020. We’ve improved the data extraction from BO4 system and the calculation behind it. Now the field “fullTimeWorkingAmount” will show the correct values from BO4. Extra field “Meerling” endpoint Maternity Leaves For both core systems HRCB and HR Core Online (BO4) we’ve added the field “multipleBirthIndication” to the endpoint Maternity Leaves. In case more than one child is expected, this can be defined in both core systems (field name in core systems: Meerling). Value “true” indicates that Multiple births are expected for this specific Maternity Leave case. Endpoint Maternity Leaves { "id": "string", "isDeleted": true, "personId": "string", "contractId": "string", "reportingDate": "2021-01-12T19:36:56.808Z", "startDate": "2021-01-12T19:36:56.808Z", "firstWorkingDay": "2021-01-12T19:36:56.808Z", "probableDeliveryDate": "2021-01-12T19:36:56.808Z", "actualDeliveryDate": "2021-01-12T19:36:56.808Z", "multipleBirthIndication": true, "extensions": [ { "key": "string", "value": "string" } ] } Extra filter on active & inactive sickness records For the endpoint /sickleaves there an additional (optional) filter available. The extra parameter is could be added while fetching all sickness records within a tenant/client. By default, the base URL of this endpoint will expose all available sickness records (active & inactive) within the specific client data set. By adding the active filter to the base URL of this endpoint, the response output will only show the current active records corresponding to this client. For example : https://api.raet.com/mlm/sickleaves?active=true Extra filter option based on ‘level’ For the endpoints /valuelists & /jobprofiles we’ve made it possible to execute an extra (optional) filter on the exposed data records. The body responses of both endpoints already expose a field “level”, which indicates the level this Job Profile or Valuelist is configured in the core system, for example, “client”, “company” or “system” level. By default the base URLs of these endpoints will expose all available jobprofile & valuelist records within the specific client data set. Example endpoint /jobprofiles { "validFrom": "2018-10-17", "validUntil": "9999-12-31", "extensions": [ { "key": "null", "value": "null" } ], "id": "AA123", "fullName": "receptionist", "level": "company", "companyCode": "20114", "isDeleted": false } By adding the level filter to the base URL of these two endpoints, the response output will only show the records corresponding to this level. For example : https://api.raet.com/mlm/jobprofiles?level=Company ... View more

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