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. ... Näytä lisää

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   ... Näytä lisää

  File types Sandbox file types File API Sandbox Uploads Name File API Sandbox Uploads Business type id 7100 Type Upload to YouServe Owner File API Info Type can be used to test the File API   File API Sandbox Downloads Name File API Sandbox Downloads Business type id 7101 Type Download to YouServe Owner File API Info Type can be used to test the File API.       HR Core Payroll Business file types Batch Input format Name Batch Input format (EN) / Batch input formaat (NL) Business type id 113001 Type Upload to YouServe Owner HR Core Payroll Business Info File Pattern: <TENANTID>_<OPTIONAL>.<EXTENSION>   Description of this type can be found in the online help of HR Core Payroll Business. Search for the keywords: "externe systemen overzicht", and follow the "batch input" description. To configure this type, ask your (payroll) consultant or account manager. Extension can be configured per individual customer. This is customer specific. The content contains text-file. Mostly used is .dat type, but any type is possible.     CSV file (one-off mutations) Name CSV file (one-off mutations) (EN) / CSV bestand (dagmutaties) (NL) old name: Payroll EMA Imports Business type id 113002 Type Upload to YouServe Owner HR Core Payroll Business Info File Pattern: <TENANTID>_<COMPANYKEYCOD>_<OPTIONAL>.csv   Description of this type can be found in the online help of HR Core Payroll Business. Search for the keywords: "externe mutaties" and follow the "CSV bestand (dagmutaties)" description. To configure this type, ask your (payroll) consultant or account manager.     Import HR Data (Excel) Name Import HR Data (Excel) Business type id 113018 Type Upload to YouServe Owner HR Core Payroll Business Info File Pattern: [tenantid]_[free text].xlsx Example 1234567_Verlofaanvraag- 20250901.xlsx.   Import HR Data in Excel file format. The empty Excel file needs to be created in HR Core through the screen Management -> Create Excel file. Then data can be added and files will be imported automatically and a processing report will appear in the Shared reports screen in HR Core. Please do not rename any of the tabs within the Excel file. Renaming tabs will prevent the file from being processed.       Journal entries Name Journal entries (EN) / Journaalposten Export (NL) Business type id 113003 Type Download from YouServe Owner HR Core Payroll Business Info File Pattern: RPD.<TENANTID>.*.*   Description of this type can be found in the online help of HR Core Payroll Business. Search for the keywords: "automatische journalisering". To configure this type, ask your (payroll) consultant or account manager. Extension can be configured per individual customer. This is customer specific depending on the financial application of the customer.     Excel base document ( fixed/period) Name Excel base document ( fixed/period) (EN) / Excel basisdocument (vast/periode) (NL) Business type id 113016 Type Upload to YouServe Owner HR Core Payroll Business Info File Pattern: <TENANTID>_<OPTIONAL>.<EXTENSION> Supported extensions: xlsx (Deprecated, still supported: <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" and follow the "Excel basisdocument" description. To configure this type, ask your (payroll) consultant or account manager.       Payslips and Annual statements Name Payslips and Annual statements Business type id 113014 Type Download from YouServe Owner HR Core Payroll Business Info File Pattern: RPD.Dossier.[tenantid].[mutkey of company]00[runnr payroll]_[current date and time in 'ticks'].zip   One delivery contains: 1 zip file with the payslips or annual statements and 1 xml file which can be used as index file for the zip file. The zip file and the xml file have the same file name. Only the extension is different. To sent the files to File API, the configuration needs to be changed in HR Core Payroll Business. This configuration change is described in the online help of HR Core Payroll Business. Search for  the keywords: "Loonstroken en jaaropgeven naar File API". To configure this type, ask your (payroll) consultant or account manager.      Tax declaration / Loonaangifte file types Name Tax declaration / Loonaangifte (NL) Business type id 102000 Type Download from YouServe Owner HR Core Payroll Business Info File Pattern: DECL.[tax declaration reference number].[yyyypp].[yyyyMMdd-HHmmss].txt   Description of this type can be found in the online help of HR Core Payroll Business. Search for the keywords: "Kopie aangifte verzenden via File API ". Configuration is done per payroll tax number (loonheffingsnummer (NL)). To configure this type, ask your (payroll) consultant or account manager.     Payment manager/ Betaalmanager (NL) file types Name Payment files /  Betaalbestanden (NL) Business type id 134001 Type Download from YouServe Owner Payroll business File Pattern SEPA-[YouServe tenantId]-[messageId]-[IBAN number]-[yyyymmdd]_[hhmmss].xml   Notes: [YouServe tenantId] = unique customer number [messageId] = payment message id   example: SEPA-3333333-1286-NL72FVLB0138782523-20241008_113108.xml   Description of this type can be found in the online help of HR Core Payroll Business. Search for the keywords: "Route betaalbestand". Configuration is done per checking account (betaalrekening (NL)). To configure this type, ask your (payroll) consultant or account manager.     UPA file for Pension and Assurance 3rd parties using Keylane Name UPA files Keylane Business type id 141001 Type Download from YouServe Owner Payroll business Info This file contains a set of employee data that can be used by pension providers and insurance companies to implement the pension regulations and process information about the premiums that have been withheld. The file complies with the so called "UPA-specifications" (Uniforme PensioenAangifte) as published by the Dutch SIVI organization.   File pattern The file names matches this pattern: UPA_[Payroll tax number]_[Message ID]_[yyyymmddhhmmss]_UPA.xml   Notes: [Payroll tax number] = Dutch [loonheffingsnummer] [messageId] = The message ID is composed as follows: [YouServe customer number]-[Payroll tax number]-[Sequence number]-[Declaration ID]   example: UPA_123456789L02_1234567-123456789L02-1-87195_20250520100332_UPA.xml   Configuration To be able to collect this file type using the File API, ask your (payroll) consultant or call our service desk. They can find the settings here:  User group: Uniforme pensioenaangifte Menu: Settings  > Declaration steering data (Instellingen > Aangifte stuurgegevens) There are two ways of working possible: If the original declaration has to be sent to the file API, and the organisation that picks up the file there will take care of all processing, choose: Aangifte verzenden via: File API Kopie Aangifte verzenden via File API: Nee If the original file has to go to the regular pension provider or insurer, and a copy has to be provided by the file API for additional purposes: Aangifte verzenden via: <choose the proper pension provider or insurer> Kopie Aangifte verzenden via Fila API: Ja   Online help In the online help from HR and Payroll you can find more explanation, search for these keywords: (Dutch) Aangifte Aangifte verzenden Aangifte stuurgegevens     UPA file for Pension and Assurance 3rd parties using Other Side at Work Name UPA files Other Side at Work Business type id 141003 Type Download from YouServe Owner Payroll business Info This file contains a set of employee data that can be used by pension providers and insurance companies to implement the pension regulations and process information about the premiums that have been withheld. The file complies with the so called "UPA-specifications" (Uniforme PensioenAangifte) as published by the Dutch SIVI organization.   File pattern The file names matches this pattern: UPA_[Payroll tax number]_[Message ID]_[yyyymmddhhmmss]_UPA.xml   Notes: [Payroll tax number] = Dutch [loonheffingsnummer] [messageId] = The message ID is composed as follows: [YouServe customer number]-[Payroll tax number]-[Sequence number]-[Declaration ID]   example: UPA_123456789L02_1234567-123456789L02-1-87195_20250520100332_UPA.xml   Configuration To be able to collect this file type using the File API, ask your (payroll) consultant or call our service desk. They can find the settings here:  User group: Uniforme pensioenaangifte Menu: Settings  > Declaration steering data (Instellingen > Aangifte stuurgegevens) There are two ways of working possible: If the original declaration has to be sent to the file API, and the organisation that picks up the file there will take care of all processing, choose: Aangifte verzenden via: File API Kopie Aangifte verzenden via File API: Nee If the original file has to go to the regular pension provider or insurer, and a copy has to be provided by the file API for additional purposes: Aangifte verzenden via: <choose the proper pension provider or insurer> Kopie Aangifte verzenden via Fila API: Ja   Online help In the online help from HR and Payroll you can find more explanation, search for these keywords: (Dutch) Aangifte Aangifte verzenden Aangifte stuurgegevens       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               ... Näytä lisää

  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     ... Näytä lisää

  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.     ... Näytä lisää

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.   ... Näytä lisää

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.     ... Näytä lisää

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   ... Näytä lisää

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   ... Näytä lisää

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.     ... Näytä lisää

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.     ... Näytä lisää

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 ... Näytä lisää

15-09-2025: new endpoint: Sites We have added a new endpoint to the WFM API: Sites. The Sites endpoint delivers the work locations of an organization registered in HR Core.  This new functionality is now accessible to all WFM API users, without reloading the data.  For detailed information about the new functionality, please refer to our knowledge base: Sites endpoint   21-08-2025: new properties to support the employee journey in HR Core Three new properties are added to the WFM API. The Endpoint Employments is extended with the properties: employmentStatus KindOfEmployment  VismaConnectId  The new properties are available after your data is reloaded. We will reload your data on your request. Please request a reload of contracts data in a support request. Documentation: Employments endpoint 09-05-2025: new filter on employments endpoint A new filter is added to the employments endpoint: personcode. Retrieve all employments of 1 employee by filtering on personcode: https://api.youserve.nl/wfm/v1.0/employments?personcode=<personcode>   29-04-2025: new entity Work pattern Today we have added the work pattern data to the WFM API. Defined in HR Core, the work pattern specifies the regular days an employee is available for scheduling. This update includes: New properties in the Employments endpoint:  A reference to the work pattern The work pattern method The date when the work pattern starts New endpoint Workpatterns This new functionality is now accessible to all WFM API users. To utilize the work pattern data, a reload of your employment data is necessary. If this is required, please reach out to the service desk to initiate the data reload. For detailed information about the new functionality, please refer to our knowledge base: Employments endpoint Workpatterns endpoint   31-03-2025: backupManager and backupManagerPersonId added to endpoint OrganizationUnits The properties backupmanager and backupMangerPersonId are added to the endpoint OrganizationUnits. To use the new properties, we have to reload your data from HR Core to our API platform. Please use a support request in Xurrent/4me to reload your data.  Description of endpoint: OrganizationUnits   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     ... Näytä lisää

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     ... Näytä lisää

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. ... Näytä lisää

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! ... Näytä lisää

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" } ] } ]       ... Näytä lisää

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" } } ] } ]     ... Näytä lisää

  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 ... Näytä lisää

  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. ... Näytä lisää

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

  Swagger documentation The following swagger page gives an overview of the endpoints: MLM API Older versions: MLM API v1 Deprecated 31-3-2024 MLM API v2 Deprecated 31-3-2024 Endpoints Companies The entity Companies contains data related to the existing sub-companies within a tenant/client.. https://api.youserve.nl/mlm/companies    Filters Single company - Retrieve specific company by adding the id of the company. GET https://api.youserve.nl/mlm/companies/<id>   Companycode - Retrieve specific company by filtering on companycode. https://api.youserve.nl/mlm/companies?companyCode=<companyCode>   Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request.  By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/companies?ChangedAfter=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.   Contracts The endpoints /employees and /contracts exposes all the corresponding details of a contract belonging to an employee. (HR Core Business: "Medewerker > Contract"). To retrieve the list of all available contracts within a tenant the Contract endpoint can be used without using any additional parameters. https://api.youserve.nl/mlm/contracts   Filters Single employment - Retrieve specific employment by adding the id of the employment. https://api.youserve.nl/mlm/contracts/<contractid>     PersonId - In case all contracts from a specific person are needed, this can be retrieved based on the “personId” https://api.youserve.nl/mlm/contracts?personId=<personId>   Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request. By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/contracts?ChangedAfter=2023-01-01T10:00:00.000Z&ChangedUntil=2023-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 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 contractCode Code of the contract. 01 91 - Contract Id company Unique (alphanumeric) code of the company (legal entity) with which the contract is concluded. 004 18 - Company code 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 Geplande laatste datum indienst (fieldnr 10520479) note: calculated field: [Geplande laatste datum indienst] = [Datum uitdienst] - 1 day   Datum uitdienst = fieldnr 40 hireDate The hire date of the employment. 2010-10-01 39 - Datum indienst employmentType (V) Type of employment like Internal Employee, Contractor, Wachtgelder shortName: Code or short name of the employment type fullName: name or full title of the employment type CNTR 7393 - Type Medewerker contractType (V) Type of the contact like indefinite period ('onbepaalde tijd') or given time ('bepaalde tijd'). Bepaalde tijd 10204687 - Contract type employmentStatus (new per 1-7-2025) Status of an employee 0 = Future Hire (no login) 1 = Future Hire 2 = Active employment 3 = Out of service 4 = Never employed 5 = Out of service (no login) 2 10529734 - Arbeidsrelatie status KindOfEmployment  (new per 1-7-2025) Indicator for external or regular employee 1 = Employee 2 = External 1 10529728 - Arbeidsrelatie soort VismaConnectId  (new per 1-7-2025) Visma Connect Identity. This value will be automatically populated when a user is created in Visma Connect 0ceee097-3b81-44a2-8cb4-1d0ce22dfad0 10530657 - Visma connect identiteit 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 Organization unit of employment. The Organization Unit contains the following details: reference Id to the OrgUnit. PD 6000 - Organisatorische eenheid fullTimeWorkingAmount Indicates the full-time hours per period within a specific company. For example 40 or 36 hours per week.  36 Uren periode (465). NB: confingured on company level.  noRisk indicator of noRisk status false (default) No Risk polis van toepassing endDateNoRisk Last date of noRisk status 2025-12-31 Einddatum no risk periode phoneNumbers: type type     phoneNumbers: number number 088-1004300 Business : 7374 - Telefoonnummer intern emailAddresses: type type     emailAddresses: address address [email protected] Business : 7212 - E-mailadres workingAmount:  amountOfWork Indicates the full-time hours per period for this employment 36 465 - Uren periode workingAmount:  unitOfWork (V) Indicator of unit type of amount of work Hours   workingAmount : periodOfWork (V) Indicates the period for which amountOfWork and unitOfWork are defined 1 463 - Dagen/uren per 1 = "Week" 2 = "FourWeeks" 3 = "Month" 4 = "Quarter" establishmentCode The location at which the employment is being fulfilled 1 7449 - Werklocatie expireDate  Date when the employment will expire 2025-12-31 7226 - afloopdatum employmentIndicator  Indicates if employment is employed or out of service 1 38 - Dienstverband indicatie 1) Employed / In Dienst 2) Out of Service / Uit Dienst parttimeFactor   1 10002071 classification (V) This property can be defined by per customer. Label can be different per customer. The values concerns the shortname of a list. This list can be requested in the valuelists endpoint with the type "classification" 474 474 - Classificatie kenmerk (NL) Classification indicator (EN) extensions: key Extra customer specific data can be added with extensions. extensions: value   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/mlm/employees    Filters PersonId/ PersonCode - In case specific person incl. contract records are needed, this can be retrieved based on the “personId” or “personCode”. https://api.youserve.nl/mlm/employees/<personId>  https://api.youserve.nl/mlm/employees?personCode=<personCode>    When person layer is enabled in HRCore Business, the PersonId is equal to PersonCode. If so, personId can also be used in filtering: https://api.youserve.nl/mlm/employees?personCode=<personId>    Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request.  https://api.youserve.nl/mlm/employees?ChangedAfter=2024-01-01T10:00:00.000Z&ChangedUntil=2024-06-01T11:00:00.000Z. Format: YYYY-MM-DDTHH:MM:SS.sssZ.   Data mapping Data from Persons and Contracts endpoint is combined in the Employees endpoint. Please check data mapping with Persons and Contracts endpoint for data mapping of Employees endpoint.   EstablishmentUnits  (Work location) - (NEW September 2025) The establishmentUnits endpoint delivers the work locations of an organization.  In HR Core the work location is supported with the menu-item Settings > General > Work location (Dutch: Instellingen > Algemeen > Werklocatie)   In the MLM API, the work location is known as establishmentCode. The establishmentCode  is delivered with Employees and Contracts endpoint: Employees.Contracts.establishmentCode = EstablishmentUnits.Code Contracts.establishmentCode = EstablishmentUnits.Code URL of the endpoint: https://api.youserve.nl/mlm/establishmentunits   Filters Single establishment unit - Retrieve 1 establishment unit by adding the id of the item. https://api.youserve.nl/mlm/establishmentunits/<id>   Code - Returns a list of all establishment units filtered by the code of the establishment unit. https://api.youserve.nl/mlm/establishmentunits?code=101    Incremental load - To retrieve only changes after last request, use the From and To in the request.  Retrieve only records which that have changed within the provided date-time (UTC) range: GET https://api.youserve.nl/mlm/establishmentunits?from=2025-01-01T09:00:00.000Z&to=2025-06-30T14:00:00.000Z . Format: YYYY-MM-DDTHH:MM:SS.sssZ.   Data mapping API field Description Example HR Core id The id of the establishment unit/ work location 658332 7449 - technical key validFrom The date from which the record is valid 2025-04-01 Reference date (Peildatum - NL) validUntil The data from which the record is no longer valid. Contains a default date 9999-12-31 in case no “end date“ has been defined for the record. 9999-12-31 2027-05-01   isDeleted Provide the active/inactive status of the record in the HR Core system. "isDeleted": false means the record is available in HR Core "isDeleted": true means the record is deleted in HR Core false   code Code of the establishment unit 51 548 - Code Referring to: Employees.Employments.Site  and Employments.Site name   Name of the establishment unit Area 51 7445 - Werklocatie naam numberKvK Chamber of commerce number DM1 7271 - Nummer KvK phoneNumber   033-1234567 7415 - Telefoonnummer emailAddress   [email protected] 7447 - E-mailadres Vestiging address description   8099 - Locatie omschrijving   street   7454 - Straat   houseNumber   7451 - Huisnummer   houseNumberSuffix   7452 - Huisnummer toev.   postalCode   7453 - Postcode   city   7446 - Plaats   country NL 8110 - Land mailingAddress locationDescription   8100 - Locatie omschrijving (postadres)   street   7383 - Straat (postadres)   houseNumber   7380 - Huisnummer (postadres)   houseNumberSuffix   7384 - Huisnummer toev. (postadres)   postalCode   7382 - Postcode (postadres)   city   7381 - Plaats (postadres)   country   7571 - Land (postadres) Extensions are not supported in this endpoint.    Jobprofiles This endpoint returns all the relevant data regarding the job profiles, like Job family information & Job profile descriptions. https://api.youserve.nl/mlm/jobprofiles JobProfiles can be configured on different levels in the core system, on ‘client level’ or on 'company level'. The endpoint will provide details regarding the the level. 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/mlm/jobprofiles/<id>     Level - Filter out specific Job Profiles corresponding to a specific “level”. https://api.youserve.nl/mlm/jobprofiles?level=client   Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request. By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/jobprofiles?ChangedAfter=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.   Maternityleaves This endpoint will provide all the needed data regarding Maternity Leave of an employee. https://api.youserve.nl/mlm/maternityleaves   Filters Single maternity leave - Retrieve specific maternity leave by adding the id of the leave. https://api.youserve.nl/mlm/maternityleaves/<id>     PersonId - In case all maternityleaves of a specific person are needed, this can be retrieved based on the “personId” https://api.youserve.nl/mlm/maternityleaves?personId=<personid>     ContractId - In case all maternityleaves of a specific contract are needed, this can be retrieved based on the “contractId” https://api.youserve.nl/mlm/maternityleaves?contractId=<contractid>     Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request. By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/maternityleaves?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 maternity leave case. This ID is unique within the entity and tenant. The ID is generated by the system and can not be changed by a user. 4320628 7593 - Key of the maternity isDeleted Provide the active/inactive status of the record in the core system. False   personId The Id of a unique person within a tenant. 10056832 10519680 - personNumber contractID Technical and unique ID. This ID is unique within the entity and tenant. The ID is generated by the system and can not be changed by a user. 34567 49 - Key of the contract reportingDate The recovery date is defined as the first day the employee appears at his work after a maternity period. (date) 7595 - Datum melding startDate Start date of the maturity leave. (date) 7594 - Begindatum verlof / WAZO actualDeliveryDate The actual date of birth of the child. (date) 7599 - Feitelijke bevallingsdatum firstWorkingDay The first day the employee appears at his work after the maturity leave period. (date) 7596 - Eerste werkdag probableDeliveryDate The probable date of delivery. (date) 7598 - Vermoedelijke bevallingsdatum multipleBirthIndication In case more then one child is expected, this can be defined in both core systems. Value “true” indicates that a Multiple birth is expected for this specific Maternity Leave case. false / true 7350 - Meerling 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/mlm/organizationunits   Filters Single organisation unit - Retrieve specific org unit by adding the id of the org unit. https://api.youserve.nl/mlm/organizationunits/<id>     Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request. By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/organizationunits?ChangedAfter=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.   Persons The endpoint persons expose all the available versions of a unique person, so historical, current, and future versions. (HRCore Business: "Medewerker > Persoon")  To retrieve the list of all active persons within a tenant the Persons endpoint can be used without using any additional parameters. https://api.youserve.nl/mlm/persons   Filters Single person - Retrieve specific person by adding the id of the person. https://api.youserve.nl/mlm/persons/<personid>     Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request. By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/persons?ChangedAfter=2023-01-01T10:00:00.000Z&ChangedUntil=2023-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 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 lastNameAtBirth The last name at birth of the employee. Also known as the family name. Vries  24 - Achternaam lastNameAtBirthPrefix The prefix of the last name at birth. de  26 - Voorvoegsel lastName The last which is currently used by the employee as his last name. Vries - Van Eijck  524 - Opgemaakte naam aanhef lastNamePrefix (not recommended to use this field. This field is the same as lastNameAtBirthPrefix) The prefix of the last name at birth. de  26 - Voorvoegsel nameAssembleOrder (V) Code of the assemble order that the core system uses for the Last Name. The assembly order is depending on the core system and the logic behind it. C  28 - Eigennaam code partnerName The partner's last name. Eijck  27 - Naam Partner partnerNamePrefix The prefix of the partner's last name. van  166 - Voorvoegsel Partner titlePrefix The formal title will be used as a prefix before the name like Doctor, Professor, etcetera. Bachelor 94 - Titel voor Description titleSuffix The formal title which will be used as postfix after the name like MSc or Master of Science. MsC 95 - Titel na Description gender (V) Gender of the person conform the ISO/IEC 5128 standard (0) Not known (1) Male (2) Female (9) Not applicable 2 P00330 - Geslacht M = Man / Male V = Vrouw / Female birthDate Date of Birth. 1990-05-25 35 - geboorte datum deceasedDate Indicated if the employee is deceased. (if True > date format) 10302568 - Datum overlijden nationalIdentificationNumber Country specific Identification number. 1744263858 10000018 - Burgerservice nummer userUID The Digital Identity of the user from the portal, to be used for SSO. a061c395-558f-49c7-991c-633aa9afa529 10523564 - Toegekende identiteit (before: PING ID) address type streetName houseNumber houseNumberAddition postalCode city country 01 Kerkstraat 26 A 3567 AH Hilversum Nederland 01 Living address / 02 Postal address 391 - straat 392 - Huisnummer 393 - Huisnummer toevoeging 394 - Postcode 395 - Woonplaats 34 - Woonland > description phoneNumbers type number 0546-453212 Home : 7376 - Telefoonnummer prive Mobile : 7377 - Telefoonnummer mobiel emailAddresses type address [email protected] 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   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/mlm/roleassignments   Filters Single roleassignment - Retrieve 1 role assignments by adding the id of the item. https://api.youserve.nl/mlm/roleassignments/<id>   OrganizationUnitId - Retrieve all roleassignments for 1 specific organizational unit: https://api.youserve.nl/mlm/roleassignments?organizationUnitId=<organizationUnitId>   Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request. By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/roleassignments?ChangedAfter=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   The information about the role can be retrieved from the valuelists endpoint:  ../valueList?type=roleUserManagement where roleassignments.shortname = valuelist.shortName fullName deprecated (may 2025) The fullname of the role    fullName is replaced by the valuelist roleUserManagement. See shortName 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.   Sickleaves Returns a list of all sick leaves for the tenant specified in the request header consisting of: https://api.youserve.nl/mlm/sickleaves  Filters Single sickleave - Retrieve specific sick leave by searching on id of the sick leave https://api.youserve.nl/mlm/sickleaves/<id>     PersonId - In case all sickleaves of a specific person are needed, this can be retrieved based on the “personId” https://api.youserve.nl/mlm/sickleaves?personId=<personid>     ContractId - In case all sickleaves of a specific contract are needed, this can be retrieved based on the “contractId” https://api.youserve.nl/mlm/sickleaves?ContractId=<contractid>     Active - to retrieve only active sickleaves, use the active parameter https://api.youserve.nl/mlm/sickleaves?active=true   Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request. By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range. https://api.youserve.nl/mlm/sickleaves?ChangedAfter=2024-01-01T10:00:00.000Z&ChangedUntil=2024-06-01T11:00:00.000Z. Format: YYYY-MM-DDTHH:MM:SS.sssZ.   Important note : All the available sickness versions will exposed as separate data records. The MLM API will expose this data as it’s received it from the core system without additional logic to merge it to one case. All the necessary technical logic to merge these records into one ‘sickness dossier’ according to the 28-days regulation has to be added at the ‘API consumer side’. Data mapping Fields marked with (V) should be connected with the results of the endpoint ‘Valuelists’. API field Description Example HR Core Business (r1) Id Technical and unique ID of the sickness registration. This unique ID is generated by the core system and can not be changed by a user. 12345678 7471 - Key of the sickness IsDeleted Provide the active/inactive status of the sickness record in the core system. False   personId The Id of a unique person within a tenant. 10056832 10519680 - personNumber contractId Technical and unique ID, which is unique within the entity and tenant. The ID is generated by the system and can not be changed by a user. 001 49 - Key of the contract reportingDate Date the sickness reported by the employer. 2024-01-01 7189 - Datum ziekmelding startDate The first date of the sickness case. 2024-01-01 7206 - Eerste verzuimdag hoursWorkedFirstDay Hours worked on the first sickness date. This could be relevant if the employee gets sick during his working day. 2,00 7423 - Gewerkte uren eerste verzuimdag expectedRecoveryDate The expected recovery date. 2024-01-08 7443 - Verwachte hersteldatum sicknessType (V) Type of sickness.   1 = Sick 2 = Illness due to pregnancy 3 = Organ donation 5 = Occupational accident 9 = Accident fault by third parties   in Dutch: 1 = Ziek 2 = Ziekte door zwangerschap 3 = Orgaandonatie 5 = Bedrijfsongeval 9 = Ongeval schuld derden 5 7107 - Soort Ziekte absenceReason Reason for absence. (string) #N/A recoveryDate The recovery date is defined as the first day the employee appears at his work after a sickness period. 2024-01-15 7207 - Eerste werkdag recourse Indicates the right of recourse when the sickness is the result of an accident caused by someone else. (boolean) 7391 - Regres ongoingSickness Indicates if the sickness case is an ongoing sickness case. This means that in the MLM system will tread as part of the previous sickness of the employee. Mostly this is the case if the previous sickness was within 28 days. (boolean) 7075 - Doorlopend ziektegeval safetynet Reason of Safetynet case   #N/A dateWVP Date of the first sickness of a series of sickness cases. In the Netherlands named ‘the 28 days rule’.   7076 - Date WVP urgentCheckRequired Indicates if an urgent check by the occupational health service is required. (boolean) 7401 - Spoedcontrole expectedFinalResult The expected final result based on the first impression by the manager. For instance, if the manager expects that the employee can fully recover without any restriction for his current Job he can set his expectation so the occupation health service can act on it. (string) 7444 - Verwacht resultaat finalResult (V) The final result after the employee is recovered. For instance, if the employee returns but in another job. (string) 7470 - Eindresultaat internalFollowUp       additionalNote        partial recovery startDate illnessPercentage 2024-01-05 80 7464 - Ziektepercentage  therapeutic period startDate endDate workingAmount workingPercentage 2024-01-07 2024-01-10 16 40  7089 - Arbeidstherapiepercentage  nursing address startDate endDate nameCareAddress streetName number numberAdditional locationDesignation postalCode city region country emailAddress phoneNumber faxNumber 2024-01-01 2024-01-10 Ziekenhuis Rijnstate Wagnerlaan 55 6815 AD Arnhem Gelderland Nederland [email protected] 088 - 005 8888 7442 - Naam verpleegadres 391 - Straat 392 - Huisnummer 393 - Huisnummer toevoeging 8099 - Locatie omschrijving 394 - Postcode 395 - Woonplaats 10205283 - Regionaam buitenland 34 - Woonland 7447 - E-mailadres 7455 - Telefoon 7375 - faxnummer extensions: key Extra customer specific data can be added with extensions. extensions: value   Value lists This endpoint returns all the corresponding code & descriptions of pairs of fields that are available in the MLM 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. The next types are available: classification contractType country employmentType department finalResult gender nameAssembleOrder organisationUnitType roleUserManagement (endpoint roleassignments.shortname) sicknessType workingUnit    In ‘Data Mapping’, the fields, which are marked with (V), these fields should be connected with the results of the endpoint ‘Valuelists’. Valuelists can be configured on different levels in the core system, on ‘client level’ or on ‘company level'. On top is these levels there are also 'system level’ Valuelists.   Output example 1 : Valuelists on (core) system level { "validFrom": "2011-01-01", "validUntil": "9999-12-31" "shortName": "1", "fullName": "Man", "type": "gender", "level": "System", "isDeleted": false, }, Output example 2 : Valuelists on client (tenant) level { "validFrom": "2018-08-10", "validUntil": "9999-12-31" "shortName": "2", "fullName": "Stagiair", "type": "employmentType", "level": "Client", "isDeleted": false, },   Retrieve all valuelists: https://api.youserve.nl/mlm/valuelists    Filters Single type - Retrieve details of a specific type of valuelist, based on the “type”. https://api.youserve.nl/mlm/valuelists/<type> example https://api.youserve.nl/mlm/valuelists/employmentType   Level - Filter out specific valuelists corresponding to a specific “level”. https://api.youserve.nl/mlm/valuelists?level=company    Combination level, type - combining the 2 above filters. https://api.youserve.nl/mlm/valuelists/function?level=company        ... Näytä lisää

  WFM API This API is intended for Work Force Management systems and allows them to get the data needed for Workforce management systems who are responsible the planning of employees of an organization: Retrieve employee data from Youforce Retrieve organizational structures from Youforce Retrieve job profile information from Youforce   Model Current implementation of WFM API supports: Person, Employee (with person endpoint), Employment, General leave, Sickness leave, Maternity leave, Job profile, Company, Organization Unit, Leave entitlements (leavebalances endpoint), Work pattern. Role Assignment is not yet supported in the WFM API. User and Assignments will not be supported in WFM. Pagination To reduce the load of an endpoint each endpoint supports paging. In case the results of an endpoint contain more than 100 records, the results set will end with a nextLink tag. Example of nextLink in the Json results:     To receive the next page of the result set, add the parameter to the request. Example: https://api.youserve.nl/WFM/v1.0/persons?nextToken=UlVTcnP2nciOaq1ExLq1G4CKk1V%252fDlIJ%252fZuazw0V4LVaufM%252fqjofpIT%252bVCZY3ctJnVakLl2vWOeJaMStJa9YmxfxvHRKVwF%252bFOWfgYmqXk6cjKJy79%252bkpB2WQP4k%252fgVWlOd1OQ%252bSnXHmAxNDotpCRXZzkyfXLZr%252bvp%252fvjJopGpX7sm4hky67J7AxBURzg9Oh&take=100   The nextLink indicates that there are more pages to load. If there is no nextLink at the end of the page, this means that it’s the last page of the result set.   Deletions After a record is deleted in the core system, the API will only return the record with his  id  and the flag  isDelete  = true. This delete means that the whole record including all version are deleted. When not deleted the value is false. The property isDeleted is always part of the output.   Example of deleted item: { "iD" : "123456" "IsDeleted":"true" } If authorisation filtering is configured for your account, then deletion of employments will cause that related persons, sickleaves, maternity leaves and leaveBalancesPayroll record can not be retrieved any longer.   Person layer in HR Core Business Person layer needs to be enabled in HR Core Business. This requirement enables a correct output of Persons and Employments endpoints.   ... Näytä lisää

  IAM API This API is intended for identity & access management systems and enabling the provisioning of users in other systems like Active Directory or IDP’s: Retrieve employee data from HR Core Business Retrieve organizational structures from HR Core Business Retrieve job profile information from HR Core Business.   Model     Pagination The IAM API supports pagination with the help of a nextToken. With the help of the following properties:  dateTime ,  validFrom  and  id  a “bookmark“ is generated ensuring no records are “lost“ when skipping through pages. Below a breakdown of the nextToken url generated at the end of the response body.     Next page token - Token generated at the end of the resultset page Date timestamp - The date timestamp of the last record of the result set page validFrom - The  validFrom  of the last record of the result set page Id - Primary key of the last record of the result set page.   Person layer in HR Core Business An additional requirement to use the Persons endpoint: the Person layer needs to be enabled in HR Core Business.    Retention time of data Retention time refers to the duration that data is stored and available in the API. In the context of GDPR legislation, it is important to define and enforce appropriate retention times to ensure personal data is not kept longer than necessary, aligning with principles of data minimization and privacy. Retention time can be defined at the API level per customer, giving them control over how long their data is stored for the purpose of APIs. To change the retention time you can create a support ticket. Please note that any changes to the retention time require a reload of the data to take effect. Each night, the system automatically evaluates and cleans up data in the API system, based on predefined retention policies. The retention time is calculated using a specific reference dates for each endpoint. The table below outlines the reference dates used per entity to determine the applicable retention period.   Endpoint reference date Companies validUntil Employees dischargedate Employments dischargedate Jobprofiles validUntil Organization Units validUntil Persons If a person has no employment, the person is no longer available in the API Role Assignments validUntil Valuelists validUntil   Example 1: Organisation Units Retention time = 30 days Data: New name for org unit C003 from "HR Advice" to "HR Advice corporate" per 1st of May 2025. { "id": "23590975", "shortName": "C003", "fullName": "HR Advice", "validFrom": "2020-01-01", "validUntil": "2025-04-30" }, { "id": "23590975", "shortName": "C003", "fullName": "HR Advice corporate", "validFrom": "2025-05-01", "validUntil": "9999-12-31" } (for demonstration means, not all data of the endpoint is shown) Retention policy, 30 days: The version (time slice) with "validFrom": "2020-01-01" to "validUntil": "2025-04-30" will be no longer available in the API on the 31st of May 2025. The 30 days of retention are passed.   Example 2: Employments Retention time = 90 days Data: no discharge date { "id": "40259407", "personCode": "1014", "personId": "1014", "employeeCode": "1014", "validFrom": "2020-01-01", "validUntil": "9999-12-31", "dischargeDate": "", "company": "500" } (for demonstration means, not all data of the endpoint is shown) No dischargedate is available, the employee is in service, employment will be available in the endpoint.   Example 3: Employments with dischargedate Retention time = 90 days Data: no discharge date { "id": "40259407", "personCode": "1014", "personId": "1014", "employeeCode": "1014", "validFrom": "2020-01-01", "validUntil": "9999-12-31", "dischargeDate": "2025-06-30", "company": "500" } (for demonstration means, not all data of the endpoint is shown) Retention policy, 90 days: The employment will be no longer available in the API on the 29th of September 2025. The 90 days of retention are passed at that time.       ... Näytä lisää

  17-10-2025: renewed user endpoint: v3 We have renewed our user endpoint. Check our news article  or full user endpoint description to find out more.   15-09-2025: new endpoint: Sites We have added a new endpoint to the IAM API: Sites. The Sites endpoint delivers the work locations of an organization registered in HR Core.  This new functionality is now accessible to all IAM API users, without reloading the data.  For detailed information about the new functionality, please refer to our knowledge base: Sites endpoint   21-08-2025: new properties to support the employee journey in HR Core Three new properties are added to the IAM API. The Endpoint Employees is extended with the properties: employmentStatus KindOfEmployment  VismaConnectId  The new properties are available after your data is reloaded. We will reload your data on your request. Please request a reload of contracts data in a support request. Documentation: Employees endpoint   25-07-2025: new valuelist type The Endpoint Valuelist is extended with the type department. Department can be used when the department property is added as an extension to the Employees or Employments endpoint. Documentation: valuelist endpoint   09-05-2025: new entity RoleAssignments Today we have added the Role assignments data to the IAM API. Defined in HR Core, the role assignment specifies the role an employee has in the organization.   This update includes: New endpoint Workpatterns Addition to Valuelists: a list of roles can be retrieved from the Valuelist endpoint This new functionality is now accessible to all IAM API users.  For detailed information about the new functionality, please refer to our knowledge base: RoleAssignments endpoint   01-03-2025: renewed user endpoint: v2 We have renewed our user endpoint. Check our news article  or full user endpoint description to find out more.   5-12-2024: properties "backupManager" and "backupManagerPersonId" added to OrganizationUnits endpoint OrganizationUnits endpoint  - The properties backupManager and backupManagerPersonId are added to the endpoint Endpoint documentation is updated. Note, we will not reload your data currently for this change. If you want to use this new property, please request a reload of the data.   04-09-2024: fix retention time On 04-09-2024 a fix will be deployed to solve an issue in het clean up of data in the IAM API.   Within the IAM API, the retention time for data is configured per customer. For most customers, this is 90 days, but this can be different per customer. Contract and employee data older then 90 days will be cleaned up in the API platform after this retention time and will not delivered anymore in the IAM API. Note: this has no effect on the data in HR Core.   We noticed that the clean up of data outside retention time was not working properly for a couple of months. Employees out of service and old contract-time slices out of retention time, were still delivered. With the fix of 4-9-2024, the data outside retention is cleaned up correctly and data in IAM API is delivered correctly. This concerns the endpoints: Employees, Employments and Persons.   12-06-2023: property "Reason For Termination Of Employment" added to Employees endpoint Employees endpoint - The property ReasonForTerminationOfEmployment is added to the Employments part of the Employees endpoint.  Endpoint documentation is updated. Note, we will not reload your data currently for this change. If you want to use this new property, please request a reload of the data.   19-05-2023: property "Reason For Termination Of Employment" added to Employments endpoint Employments endpoint - The property ReasonForTerminationOfEmployment is added to the Employments endpoint.  Endpoint documentation is updated.   05-04-2023: property language added to Employees endpoint Employees endpoint - The property language is added to the Employees endpoint.  Endpoint documentation is updated.   15-06-2022: property Enddate added to Employees endpoint Employees endpoint - Employees endpoint hold employee as well as employment data. In the Employments section, the property Enddate is added. Swagger and endpoint documentation is  also updated.   12-05-2022: change of description of user endpoint User endpoint - The description of employeeId reference has changed. The employeeId does references to the PersonCode of the employee, not to the mutKey of the employee.  https://api.youserve.nl/iam/v1.0/users(employeeId=12345) Old text: employeeId - The unique id assigned to an employee. This id is available in the Employees endpoint with the property id. New: employeeId - The unique id assigned to an employee. This value is available in the Employees endpoint with the property PersonCode. The description of the user endpoint : IAM User endpoint.   29-04-2022: User endpoint The description of the user endpoint is added to the documentation: IAM User endpoint.   01-01-2022: New endpoint: Companies For more detailed information on the endpoint please refer to below documentation: Companies endpoint. ... Näytä lisää

2021-07 Increase of performance From 5th of July up and till 9th of July a technical update on the IAM API will be deployed. The technical update will result in faster responses of the IAM API endpoints. To roll out this technical update to all consumers of the IAM API, a reload of data from HR Core to the API platform is needed for each consumer of the API. During this reload, you might receive an error on the endpoints. This is only temporarily. Please try again after some minutes.   2021-08 Clean-up process for historical records On daily base the system will clean-up the API data for historical records in the API. This clean-up process will remove all versions older than the default retention time of 90 days and also remove old-employees with a discharge date before this 90 days criteria.  Note:  It's possible that some customers deviate their retention of the historical records and keep them longer than the default 90 days.  With the new clean-up mechanism we will respect the retention time as is configured for the customer. ... Näytä lisää

2020-10 The IAM API has been expanded with the following endpoint: Employments: The employments endpoint returns employments based on id. The following filters are supported PersonCode PersonId Company OrganizationUnit validFrom validUntil mutation retrieval based on from and to dates 2020-11 Persons endpoint The IAM API has been expanded with the following endpoint: Persons The persons endpoint returns employee personalia data based on id. Value list endpoint The value list endpoint now supports filtering based on configuration levels. As part of HRCB customers are able to configure value list properties on different levels. The new filtering allows to retrieve value list based on: levels companyCode Job profiles endpoint The job profiles endpoint now supports filtering based on company codes. The new filtering allows to retrieve job profiles based on: companyCode     ... Näytä lisää

  Swagger documentation The following swagger page gives an overview of the endpoints:   IAM API Endpoints Companies GET companies The endpoint GET companies gives a list of company versions of the tenant. GET https://api.youserve.nl/iam/v1.0/companies   Retrieve 1 company by adding the id of the company: GET https://api.youserve.nl/iam/v1.0/companies/<id>   Retrieve only records which that have changed within the provided date-time (UTC) range: GET https://api.youserve.nl/iam/v1.0/companies?from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z. Format:  YYYY-MM-DDTHH:MM:SS.sssZ Data mapping Property Description Example HR Core Business id identifier of the company     mutkey shortName short name of the company     company code fullName full name of the company     company name validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A   Employees GET employees The endpoint GET employees gives a list of employees with the personal and employment details of an employee. GET https://api.youserve.nl/iam/v1.0/employees    The employee endpoint supports the following query string parameters Parameter Description   <id> Retrieve 1 employee by adding the id of the employee. https://api.youserve.nl/iam/v1.0/employees/<id>  Important note: Only the time slices valid today will be returned. If an employee has a start date in the future, this employee will not be delivered using getById.   personCode Returns a list of employee records filtered by personId https://api.youserve.nl/iam/v1.0/employees ?personCode=191166   personId Returns a list of employee records filtered by personId https://api.youserve.nl/iam/v1.0/employees ?personId=191166   company Returns a list of all employee records filtered by company https://api.youserve.nl/iam/v1.0/employees?company=1010A    organizationUnit Returns a list of all employee records filtered by organizationUnit id https://api.youserve.nl/iam/v1.0/employees?organizationUnit=13612345    from and to Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/iam/v1.0/employees?from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   isActive Allows to filter out inactive records, returns all records that have been “deactivated“ either due to: Deletion of the record (employee) in the core application itself https://api.youserve.nl/iam/v1.0/employees?isActive=false   validFrom   Returns a list of employee records filtered based on the validFrom and validUntil Date timestamp format is always according to ISO 8601 YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/employees?validFrom=2020-11-07   validUntil Returns a list of employee records filtered based on the validUntil Date timestamp format is always according to ISO 8601 YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/employees ?validUntil=2020-11-09     Data mapping Property Description Example HR Core Business id The globally unique id assigned to an employee 12345678 N/A Mutkey medewerker personCode The unique id assigned to the employee 32789 7014 Uniek Persoonlijk ID (UPI)* personId The globally unique id assigned to an employee 12345678 10519680 Persoon nummer initials The initials of the employee A.B. 25 Voorletters firstNames The official given names of the employee Amy Beatrice 51 Voornamen knownAs The name which is used by the employee as first name Amy 165 Roepnaam lastNameAtBirth The last name at birth of the employee. Also known as the family name Vries 24 Achternaam lastNameAtBirthPrefix The prefix of the employee's last name at birth de 26 Voorvoegsels lastName The last name used by the employee at present de Vries - van Eijck 524 Opgemaakte naam aanhef The value is determined by the setting in nameAssembleOrder lastNamePrefix (not recommended to use this field. This field is the same as lastNameAtBirthPrefix) The prefix of the employee's last name at birth de 26 Voorvoegsels nameAssembleOrder Code of the assemble order used by the core system for the last name. Values: 0 = Partner's name + own last name 1 = Own last name only 2 = Partner's name only 3 = Own last name + partner's name 4 = Compound surname 3 28 Eigennaam code partnerName The last name of the employee's partner Eijck 27 Naam Partner partnerNamePrefix The prefix of the partner's last name Van 166 Voorvoegsels Partner titlePrefix Formal title prefix drs. 94 Titel voor titleSuffix Formal title suffix Msc 95 Titel na gender Gender of the employee Female 36 Geslacht   dateOfBirth Date of birth 1986-12-02 35 geboorte datum deceased This field indicates if an employee is deceased when false the property is not returned true 10302568 Datum overlijden language Language of employee DE - German FR - French EN - English NL - Dutch NL 10 Taal employmentStatus (new per 1-8-2025) Status of an employee 0 = Future Hire (no login) 1 = Future Hire 2 = Active employment 3 = Out of service 4 = Never employed 5 = Out of service (no login) 2 10529734 Arbeidsrelatie status KindOfEmployment  (new per 1-8-2025) Indicator for external or regular employee 1 = Employee 2 = External 1 10529728 Arbeidsrelatie soort VismaConnectId  (new per 1-8-2025) Visma Connect Identity. This value will be automatically populated when a user is created in Visma Connect 0ceee097-3b81-44a2-8cb4-1d0ce22dfad0 10530657 Visma connect identiteit validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A phoneNumbers List of phone numbers and types Home +3188 123 45 67 7376 Telefoonnummer privé Business +3188 345 67 89 7374 Telefoonnummer intern Mobile +316 12 34 56 78 7377 Telefoonnummer mobiel emailAddresses List of email addresses of the employee Business [email protected]  7212 E-mailadres Private [email protected]  7213 E-mailadres privé Addresses List of addresses   type Home street Kerkstraat 391 Straat houseNumber 1 392 Huisnummer houseNumberAddition C 393 Huisnummer toevoeging additionalAddressLine 2nd floor 8099  Locatie omschrijving postalCode 1234 AB 394 Postcode city Amersfoort 395 Woonplaats country NL 34 Woonland   type Postal street Poststraat 7572 Straat (postadres) houseNumber 1 7573 Huisnummer (postadres) houseNumberAddition A 7574 Huisnummer toev (postadres) additionalAddressLine 2nd floor 8100 Locatie omschrijving (postadres) postalCode 1234 AB 7575 Postcode (postadres) city Amersfoort 7576 Plaats (postadres) country NL 7571 Land (postadres) Employments employeeCode The code of the employee or employment 12345 22 Medewerker code contractId Unique Id for the contract and/or employment 654789 49 Contract mutkey contractCode Code of the contract 1 91 Contract id originalHireDate The first hire date or original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee 2010-10-01 308 Datum in dienst organisatie dischargeDate The end date or discharge date of the employee. This is always an "up to and including" date. The field will always be in the response, even if the field is not filled. 2018-12-31 10520479 Geplande laatste datum indienst note: calculated field: [Geplande laatste datum indienst] = [Datum uitdienst] - 1 day   Datum uitdienst = fieldnr 40 hireDate Date of hire for the employment 2017-05-01 39 Datum indienst endDate Enddate of contract 2022-12-31 7226 Afloopdatum company Unique identifier of company the where contract is concluded 001 18 Bedrijfscode location The location at which the employment is being fulfilled AMF 75 Vestiging site The location at which the employment is being fulfilled Vestiging 1 7449 Werklocatie costCenter The cost center under which the employment is registered 012 53 Kostenplaats ReasonFor Termination OfEmployment Reason why the employment was ended 20 (lookup table below) 10528113 Reden einde arbeidsverhouding classification This property can be defined by per customer. Label can be different per customer. The values concerns the shortname of a list. This list can be requested in the valuelists endpoint with the type "classification" 123 474 Classifiecatiekenmerk 1 employmentType Code of the employment type 4 7393 Type medewerker workingAmount Working amount of the employment. amountOfWork: numeric value representing the work amount 40   465 Uren periode periodOfwork: indicates the period for which amountOfWork and unitOfWork are defined Day Week Month Quarter 463 Dagen/uren per Week Maand jobProfile The job profile code 9909 DEV 97 Functie organizationUnit The organization unit id 1234567 ZKH 6000 Mutkey organisatorische eenheid   Lookup table ReasonForTerminationOfEmployment code English Dutch/ NL 01 Term./dismissal employer within probationary per. Opzegging/ontslag werkgever binnen de proeftijd 03 Dissolution by court at request employer Ontbinding door rechter op verzoek werkgever 04 Termination mutual consent employer Beëindiging wederzijds goedvinden werkgever 05 Termination by employer long-term work incapacity Opzegging door wg langdurig arbeidsongeschikt 06 Termination by employer economic reasons Opzegging door wg bedrijfseconomische redenen 20 Termination initiative of the employee Einde arbeidsverhouding opzegging werknemer 21 Termination by employer for urgent reasons Opzegging door werkgever om dringende reden 30 Term operat. law due expiry of empl relationsh Einde rechtsw. verstr. duur arb.verh bep.tijd 31 Term operat. of law by another reason(pension,etc) Einde van rechtswege om andere reden (pens. ed) 40 End temporay emplmnt contr hirer due to ilness Einde uitzendovrk, uitz.bed inlener ziekte uitzkr 41 End of temporay emplmnt contract by hirer for aor Einde uitzendovrk, uitz.bed inlener om and. reden 50 Dismissal of public-law appointm. incompetence Ontslag publiekrecht. aanst. vw onbekwaamheid 51 Dismissal of public-law appointm age/retirement Ontslag publiekr. aanst. vw leeftijd/pensionering 90 The empl relationsh continues, but I.R.S adm. term Arb.verh loopt door, inkom.verh adm. beëindigd 91 The empl relationsh continues with new employer De arbeidsverh. loopt door bij nieuwe werkgever 92 Empl. rel.ship is followed w/o interr. same Empl. Arb.verh zonder onderbr opgevolgd bij zelfde WG 99 Another reason not mentioned above Een andere, hiervoor niet genoemde reden       Employments GET employments The employee endpoint returns information about the employments registered in HRCB. GET https://api.youserve.nl/iam/v1.0/employments   The employees endpoint supports the following query string parameters Parameter Description   <id> Retrieve 1 employment by adding the id of the employee. https://api.youserve.nl/iam/v1.0/employments/<id>  Important note: Only the time slices valid today will be returned. If an employment  has a start date in the future, this emploment will not be delivered using getById.   personCode Returns a list of employments records filtered by personId https://api.youserve.nl/iam/v1.0/employments?personCode=191166   personId Returns a list of employments records filtered by personId https://api.youserve.nl/iam/v1.0/employments?personId=191166   company Returns a list of all employments records filtered by company https://api.youserve.nl/iam/v1.0/employments?company=1010A    organizationUnit Returns a list of all employments records filtered by organizationUnit id https://api.youserve.nl/iam/v1.0/employments?organizationUnit=13612345    from and to Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/iam/v1.0/employments?from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   isActive Allows to filter out inactive records, returns all records that have been “deactivated“ either due to: Deletion of the record (employee) in the core application itself https://api.youserve.nl/iam/v1.0/employments?isActive=false   validFrom Returns a list of employments records filtered based on the validFrom and validUntil Date timestamp format is always according to ISO 8601 YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/employments?validFrom=2020-11-07   validUntil Returns a list of employments records filtered based on the validUntil Date timestamp format is always according to ISO 8601 YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/employments?validUntil=2020-11-09     Data mapping Property Description Example HR Core Business id Employment id 12459897 49 Contract mutkey personCode The unique id assigned to the employee 32789 7014 Uniek Persoonlijk ID (UPI)* personId The globally unique id assigned to an employee 12345678 10519680 Persoon nummer * employeeCode The code of the employee or employment 12345 22 Medewerker code contractCode Code of the contract 1 91 Contract id validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A originalHireDate The first hire date or original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee 2010-10-01 308 Datum in dienst organisatie dischargeDate The end date or discharge date of the employee. This is always an "up to and including" date. In case of no values the field will not be returned as part of the response body 2018-12-31 10520479 Geplande laatste datum indienst note: calculated field: [Geplande laatste datum indienst] = [Datum uitdienst] - 1 day   Datum uitdienst = fieldnr 40 enddate Enddate of contract 2022-12-31 7226 Afloopdatum hireDate Date of hire for the employment 2017-05-01 39 Datum in dienst company Unique identifier of company the where contract is concluded 001 18 Bedrijfscode location The location of where the employment is being performed 789 75 Vestiging site The location at which the employment is being fulfilled Vestiging 1 7449 Werklocatie costCenter The cost center under which the employment is registered 012 53 Kostenplaats ReasonFor Termination OfEmployment   Reason why the employment was ended 20 (lookup table below) 10528113 Reden einde arbeidsverhouding classification Cost allocation of the employment 123 474 Classifiecatiekenmerk 1 employmentType Code of the employment type 4 7393 Type medewerker jobProfile The job profile code 9909 DEV 97 Functie organizationUnit The organization unit id 1234567 ZKH 6000 Mutkey organisatorische eenheid emailAddresses List of email addresses   Business [email protected] 7212 E-mailadres phoneNumbers List of phone numbers and types Business +3188 345 67 89 7374 Telefoonnummer intern workingAmount Working amount of the employment. amountOfWork: numeric value representing the work amount 40   465 Uren periode periodOfwork: indicates the period for which amountOfWork and unitOfWork are defined Day Week Month Quarter 463 Dagen/uren per Week Maand   Lookup table ReasonForTerminationOfEmployment code English Dutch/ NL 01 Term./dismissal employer within probationary per. Opzegging/ontslag werkgever binnen de proeftijd 03 Dissolution by court at request employer Ontbinding door rechter op verzoek werkgever 04 Termination mutual consent employer Beëindiging wederzijds goedvinden werkgever 05 Termination by employer long-term work incapacity Opzegging door wg langdurig arbeidsongeschikt 06 Termination by employer economic reasons Opzegging door wg bedrijfseconomische redenen 20 Termination initiative of the employee Einde arbeidsverhouding opzegging werknemer 21 Termination by employer for urgent reasons Opzegging door werkgever om dringende reden 30 Term operat. law due expiry of empl relationsh Einde rechtsw. verstr. duur arb.verh bep.tijd 31 Term operat. of law by another reason(pension,etc) Einde van rechtswege om andere reden (pens. ed) 40 End temporay emplmnt contr hirer due to ilness Einde uitzendovrk, uitz.bed inlener ziekte uitzkr 41 End of temporay emplmnt contract by hirer for aor Einde uitzendovrk, uitz.bed inlener om and. reden 50 Dismissal of public-law appointm. incompetence Ontslag publiekrecht. aanst. vw onbekwaamheid 51 Dismissal of public-law appointm age/retirement Ontslag publiekr. aanst. vw leeftijd/pensionering 90 The empl relationsh continues, but I.R.S adm. term Arb.verh loopt door, inkom.verh adm. beëindigd 91 The empl relationsh continues with new employer De arbeidsverh. loopt door bij nieuwe werkgever 92 Empl. rel.ship is followed w/o interr. same Empl. Arb.verh zonder onderbr opgevolgd bij zelfde WG 99 Another reason not mentioned above Een andere, hiervoor niet genoemde reden     Jobprofiles GET jobprofiles The jobProfiles endpoint returns information about the job profiles (Dutch: "Functie informatie") registered. GET https://api.youserve.nl/iam/v1.0/jobprofiles   The endpoint supports the following query string parameters Parameter Description   <id> (Deprecated May 2021) Retrieve 1 jobprofile by adding the id of the employee. https://api.youserve.nl/iam/v1.0/jobProfiles/<id>    shortName Returns a list of all jobprofile records filtered by shortName https://api.youserve.nl/iam/v1.0/jobprofiles?shortname=191166   companyCode Returns a list of valueList records based on companyCode https://api.youserve.nl/iam/v1.0/jobprofiles?companycode=191166   from and to Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/iam/v1.0/jobprofiles?from=2020-01-01T09:00:00.000Z&to=2020-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   isActive Allows to filter out inactive records, returns all records that have been “deactivated“ either due to: Deletion of the record (employee) in the core application itself https://api.youserve.nl/iam/v1.0/jobprofiles?isActive=false   validFrom Returns a list of jobprofiles records filtered based on the validFrom and validUntil Date timestamp format is always according to ISO 8601 YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/jobprofiles?validFrom=2020-11-07   validUntil Returns a list of jobprofiles records filtered based on the validUntil Date timestamp format is always according to ISO 8601 YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/jobprofiles?validUntil=2020-11-09       Data mapping Property Description Example HR Core Business shortName Code or short name of the Job Profile SE 97 Functie code fullName Name or full title of the Job Profile Software Engineer 5 97 Functie omschrijving jobTitle Job title description Senior Software Developer 932 Visitekaartje validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A   Organization Units GET organization units The endpoint organizationUnits gives a list of organizationUnits versions of the tenant. GET https://api.youserve.nl/iam/v1.0/organizationunits   The endpoint supports the following query string parameters Parameter Description   <id> Retrieve 1 organization unit by adding the id of the employee. https://api.youserve.nl/iam/v1.0/organizationunits/<id>    shortName Returns a list of all organizationUnits records filtered by shortName https://api.youserve.nl/iam/v1.0/organizationunits?personCode=191166   from and to Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/iam/v1.0/organizationunits?from=2022-01-01T09:00:00.000Z&to=2022-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   isActive Allows to filter out inactive records, returns all records that have been “deactivated“ either due to: Deletion of the record (employee) in the core application itself https://api.youserve.nl/iam/v1.0/organizationunits?isActive=false   validFrom Deprecated Returns a list of organizationunits records filtered based on the validFrom and validUntil Date timestamp format is always according to ISO 8601 YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/organizationunits?validFrom=2022-11-07   validUntil Deprecated Returns a list of organizationunits records filtered based on the validUntil Date timestamp format is always according to ISO 8601 YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/organizationunits?validUntil=2022-11-09     Data mapping Property Description Example HR Core Business id Unique id of the organization unit 12345678 N/A Mutkey organisatorische eendheid shortName Code or short name of the Organization Unit PD 548 Code organisatorische eenheid fullName Name or full title of the Organization Unit Product Development 549 Naam organisatorische eenheid parentOrgUnit Code of the parent organization unit PD_EU 6000 Bovenliggende organisatorische eenheid organizationUnitType Type of organization unit Divisie 7475 Type organisatorische eenheid manager Unique id of the manager 1234567 N/A Mutkey medewerker/ mutkey employee.  Mutkey employee can be found in employees endpoint, property id managerPersonId The globally unique id assigned to an the management employee 12345678 10519680 Persoon nummer * backupManager backup manager of org unit 4005614 7011 Backup manager (mutkey of employee) Mutkey employee can be found in employees endpoint, property id backupManagerPersonId PersonCode of the Backup manager of the Organization Unit. 12345678 10519680 Persoon nummer Corresponds with: Endpoint: Employees, Property: peronId or Endpoint: Person, Property: id validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The date from which the record is no longer valid. Will contains a default date in case no “end date“ has been defined for the record. 2020-05-01   9999-12-31 N/A  N/A   Persons In order to work with the Persons endpoint, the Person layer needs to be enabled in HR Core Business.  GET Persons The endpoint persons gives a list of all persons (HRCore Business: "Medewerker > Persoon")) of the tenant. GET https://api.youserve.nl/iam/v1.0/persons   The endpoint supports the following query string parameters Parameter Description   <id> Retrieve 1 person by adding the id of the employee. https://api.youserve.nl/iam/v1.0/persons/<id>    from and to Retrieve only records which that have changed within the provided date-time (UTC) range https://api.youserve.nl/iam/v1.0/persons?from=2022-01-01T09:00:00.000Z&to=2022-01-01T14:00:00.000Z Format:  YYYY-MM-DDTHH:MM:SS.sssZ   isActive Allows to filter out inactive records, returns all records that have been “deactivated“ either due to: Deletion of the record (employee) in the core application itself https://api.youserve.nl/iam/v1.0/persons?isActive=false   personCode Retrieve all time slices of 1 person. https://api.youserve.nl/iam/v1.0/persons?personCode=<personcode>    validFrom Returns a list of persons records filtered based on the validFrom and validUntil Date timestamp format is always according to ISO 8601 YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/persons?validFrom=2022-11-07   validUntil Returns a list of persons records filtered based on the validUntil Date timestamp format is always according to ISO 8601 YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/persons?validUntil=2022-11-09     Data mapping Property Description Example HR Core Business id The globally unique id assigned to an employee 12345678 10519680 Persoon nummer personCode The unique id assigned to the employee 32789 7014 Uniek Persoonlijk ID (UPI)* initials The initials of the employee A.B. 25 Voorletters firstNames The official given names of the employee Amy Beatrice 51 Voornamen knownAs The name which is used by the employee as first name Amy 165 Roepnaam lastNameAtBirth The last name at birth of the employee. Also known as the family name Vries 24 Achternaam lastNameAtBirthPrefix The prefix of the employee's last name at birth de 26 Voorvoegsels lastName The last name used by the employee at present de Vries - Van Eijck 524 Opgemaakte naam aanhef The value is determined by the setting in nameAssembleOrder lastNamePrefix (not recommended to use this field. This field is the same as lastNameAtBirthPrefix) The prefix of the employee's last name at birth de 26 Voorvoegsels nameAssembleOrder Code of the assemble order used by the core system for the last name. Values: 0 = Partner's name + own last name 1 = Own last name only 2 = Partner's name only 3 = Own last name + partner's name 4 = Compound surname 3 28 Eigennaam code partnerName The last name of the employee's partner Eijck 27 Naam Partner partnerNamePrefix The prefix of the partner's last name Van 166 Voorvoegsels Partner titlePrefix Formal title prefix drs. 94 Titel voor titleSuffix Formal title suffix Msc 95 Titel na gender Gender of the employee Female 36 Geslacht   dateOfBirth Date of Birth 1986-02-12 N/A N/A deceased This field indicates if an employee is deceased when false the property is not returned true 10302568 Datum overlijden validFrom The date from which the record is valid 2020-04-01 N/A Peildatum validUntil The data from which the record is no longer valid. Contains a default date in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01 N/A N/A phoneNumbers List of phone numbers and types Home +3188 123 45 67 7376 Telefoonnummer privé Mobile +316 12 34 56 78 7377 Telefoonnummer mobiel emailAddresses List of email addresses of the employee Private [email protected] 7213 E-mailadres privé Addresses List of addresses   type Home street Kerkstraat 391 Straat houseNumber 1 392 Huisnummer houseNumberAddition C 393 Huisnummer toevoeging additionalAddressLine 2nd floor 8099  Locatie omschrijving postalCode 1234 AB 394 Postcode city Amersfoort 395 Woonplaats country NL 34 Woonland   type Postal street Poststraat 7572 Straat (postadres) houseNumber 1 7573 Huisnummer (postadres) houseNumberAddition A 7574 Huisnummer toev (postadres) additionalAddressLine 2nd floor 8100 Locatie omschrijving (postadres) postalCode 1234 AB 7575 Postcode (postadres) city Amersfoort 7576 Plaats (postadres) country NL 7571 Land (postadres)   Role Assignments - (NEW May 2025) The Role assignments endpoint delivers the role an employee has in the organization.  https://api.youserve.nl/iam/v1.0/roleassignments In HR Core this is supported with the menu-item Role assignment user management (EN) (Dutch: Roltoewijzing UM)   Filters Single roleassignment - Retrieve 1 role assignments by adding the id of the item. https://api.youserve.nl/iam/v1.0/roleassignments/<id>   PersonId - Returns a list of all role assignment records filtered by personId https://api.youserve.nl/iam/v1.0/roleassignments?personId=1010A    shortName - Returns a list of all role assignment records filtered by the shortName of the role. https://api.youserve.nl/iam/v1.0/roleassignments?shortName=1   Incremental load - To retrieve only changes after last request, use the From and To in the request.  Retrieve only records which that have changed within the provided date-time (UTC) range: GET https://api.youserve.nl/iam/v1.0/roleassignments?from=2025-01-01T09:00:00.000Z&to=2025-06-30T14: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 assignment 658332 960 - Key of the role assignment organizationUnit 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 includingChildOrgUnits   Refers to the level of authorisation of a specific role within an organisation. true/false Incl child OE's [913] shortName The shortname of the role  DM1 549 - (short)name of the role assignment The information about the role can be retrieved from the valuelists endpoint:  ../valueList?type=roleUserManagement where roleassignments.shortname = valuelist.shortName personId The Id of a unique person within a tenant. 10056832 10519680 - personNumber Referring to: Persons.id startDate Start date of the role assignment 2020-01-01   endDate End date of the role assignment 9999-12-31   validFrom The date from which the record is valid 2025-04-01 Reference date (Peildatum - NL) validUntil The data from which the record is no longer valid. Contains a default date 9999-12-31 in case no “end date“ has been defined for the record. 9999-12-31 2020-05-01   isActive Shows if the record is Active in HR Core. isActive=false means: logical deleted in HR Core (no longer visible in HR Core)     Extensions are not supported in this endpoint.     Sites (Work location) - (NEW September 2025) The Sites endpoint delivers the work locations of an organization.  In HR Core the work location is supported with the menu-item Settings > General > Work location (Dutch: Instellingen > Algemeen > Werklocatie)   In the IAM API, the work location is known as site. The code of the site is delivered with the Employees and Employments endpoint: Employees.Employments.Site = Sites.Code Employments.Site = Sites.Code URL of the endpoint: https://api.youserve.nl/iam/v1.0/sites   Filters Single site - Retrieve 1 site by adding the id of the item. https://api.youserve.nl/iam/v1.0/sites/<id>   Code - Returns a list of all sites filtered by the code of the site. https://api.youserve.nl/iam/v1.0/sites?code=101    Incremental load - To retrieve only changes after last request, use the From and To in the request.  Retrieve only records which that have changed within the provided date-time (UTC) range: GET https://api.youserve.nl/iam/v1.0/sites?from=2025-01-01T09:00:00.000Z&to=2025-06-30T14:00:00.000Z . Format: YYYY-MM-DDTHH:MM:SS.sssZ.   Data mapping API field Description Example HR Core id The id of the site/ work location 658332 7449 - technical key validFrom The date from which the record is valid 2025-04-01 Reference date (Peildatum - NL) validUntil The data from which the record is no longer valid. Contains a default date 9999-12-31 in case no “end date“ has been defined for the record. 9999-12-31 2027-05-01   isDeleted Provide the active/inactive status of the record in the HR Core system. "isDeleted": false means the record is available in HR Core "isDeleted": true means the record is deleted in HR Core false   code Code of the site 51 548 - Code Referring to: Employees.Employments.Site  and Employments.Site name   Name of the site Area 51 7445 - Werklocatie naam numberKvK Chamber of commerce number DM1 7271 - Nummer KvK phoneNumber   033-1234567 7415 - Telefoonnummer emailAddress   [email protected] 7447 - E-mailadres Vestiging address description   8099 - Locatie omschrijving   street   7454 - Straat   houseNumber   7451 - Huisnummer   houseNumberSuffix   7452 - Huisnummer toev.   postalCode   7453 - Postcode   city   7446 - Plaats   country NL 8110 - Land mailingAddress locationDescription   8100 - Locatie omschrijving (postadres)   street   7383 - Straat (postadres)   houseNumber   7380 - Huisnummer (postadres)   houseNumberSuffix   7384 - Huisnummer toev. (postadres)   postalCode   7382 - Postcode (postadres)   city   7381 - Plaats (postadres)   country   7571 - Land (postadres) Extensions are not supported in this endpoint.         Valuelists GET valuelists The valueList endpoint returns the descriptions to the codes returned in the IAM entity endpoints. The valueList can be configured on different levels; system  - The 1st level a valueList property can be defined, this is the highest level on which the valueList can be defined and concerns general properties such as “country” client  - The 2nd level, these valueList items are defined on the tenant level and generally defined by the customer company  - The 3rd level, these valueList items are defined on company level, meaning only relevant for the specific company the properties are defined for The company code is returned as part of the company type GET https://api.youserve.nl/iam/v1.0/valuelist  retrieves all valuelist items   GET https://api.youserve.nl/iam/v1.0/valuelist?type=[valulist type]  retrieves only the valuelists of a specific type. Example: retrieve all locations: https://api.youserve.nl/iam/v1.0/valueList?type=location   In table below, the types are shown, along with the endpoint where they are referenced. IAM property Valuelist type Persons nameAssembleOrder nameAssembleOrder gender gender Employees nameAssembleOrder nameAssembleOrder employmentType   gender gender country country costCenter costCenter classification classification location location department (as an extension) department Employments endpoint costCenter costCenter classification classification employmentType employmentType location location department (as an extension) department OrganizationUnits endpoint organizationUnitType organisationUnitType RoleAssignments endpoint shortName roleUserManagement example: <base url>/valueList?type=roleUserManagement   The endpoint supports the following query string parameters Parameter Description <type> Retrieve only 1 valuelist type,  for instance retrieve all countries: https://api.youserve.nl/iam/v1.0/valueList/country level Returns a list of valuelist records based on the level. https://api.youserve.nl/iam/v1.0/valuelist?level=client  companyCode Returns a list of valuelist records based on companyCode https://api.youserve.nl/iam/v1.0/valuelist?companyCode=2  validFrom Returns a list of valuelist records filtered based on the validFrom and validUntil Date timestamp format is always according to ISO 8601 YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/valuelist?validFrom=2022-11-07 validUntil Returns a list of valuelist records filtered based on the validUntil Date timestamp format is always according to ISO 8601 YYYY-MM-DD This is a range filter the response will contain records from the defined date until the latest possible date https://api.youserve.nl/iam/v1.0/valuelist?validUntil=2022-11-09   User (v3) The user endpoint supports the retrieval (GET) and update (PATCH) of user related data from HR Core. Base URL of user endpoint:   https://api.youserve.nl/iam/v3.0/users   GET Allows retrieving user related data from HR Core of a single employee. Data can be retrieved using several parameters: personcode or mutkey of the employee (getById).   PersonCode https://api.youserve.nl/iam/v3.0/users?personcode=[personcode]  The personcode matches the personcode in the endpoints Employees and Employments Example: https://api.youserve.nl/iam/v3.0/users?personcode=1012    getById https://api.youserve.nl/iam/v3.0/users/[id]  The id matches the mutkey of the employee which can be found in the endpoint Employees (employees.id) Example: https://api.youserve.nl/iam/v3.0/users/36457840    Datamapping Property Description Corresponds with HR Core field assignedIdentity (v2 property name: id) User id of the employee used in the Youforce authentication system (PING) or the Visma Connect Identity   Example:  c7e230db-2a7f-4ef0-ad1d-9d30e7d94a2f Toegekende identiteit (before: PING Identiteit) (NL) Assigned identity (before: PING Identity) (ENG)   Elementnumber: 10523564   loginPortalEmailAddress (v2 property name: identityId) Email address which is used for login of YouServe portal   Example: [email protected]   NL: E-mail adres (Login Portaal) (before: Identity)   ENG:  Email address (Login Portal) (before: Identity)   Elementnumber: 7013   businessEmailAddress Business email address   Example: [email protected]     E-mail adres (zakelijk) (NL) Email address (business) (ENG)   Elementnumber: 7212   privateEmailAddress Personal email address of employee   Example: [email protected]   E-mail adres (privé) (NL) Email address (private) (ENG)   Elementnumber: 7213   employmentStatus (new per 17-10-2025) Status of an employee 0 = Future Hire (no login) 1 = Future Hire 2 = Active employment 3 = Out of service 4 = Never employed 5 = Out of service (no login)   Arbeidsrelatie status (NL) Employment status (ENG)   Elementnumber: 10529734   kindOfEmployment  (new per 17-10-2025) Indicator for external or regular employee 1 = Employee 2 = External Arbeidsrelatie soort (NL) Kind of employment (ENG)   Elementnumber: 10529728   vismaConnectId  (new per 17-10-2025) Visma Connect Identity. This value will be automatically populated when a user is created in Visma Connect   Example: 0ceee097-3b81-44a2-8cb4-1d0ce22dfad0   Visma connect identiteit (NL) Visma connect identity (ENG)   Elementnumber: 10530657 startDateLogin (new per 17-10-2025) Starting from this date an employee is able to login prior to the start of his contract. This date can be used as changeDate in the PATCH.   Begindatum login (NL) Startdate login (ENG)   Elementnumber: 10529730   hireDate (new per 17-10-2025) Date of hire for the employment This date can be used as changeDate in the PATCH. Datum indienst (NL) Date service (ENG)   Elementnumber: 39   * Either the startDateLogin is in the response or the hireDate. The following rule applies: startDateLogin is delivered when employee is not yet in service (today earlier then hireDate).  HireDate is delivered when the employee is in service (today is later or equal to hireDate)   PATCH Allows to update user related data in HR Core. Use the personcode or mutkey of the employee to update the data:   Examples: https://api.youserve.nl/iam/v3.0/users?personcode=1012  or https://api.youserve.nl/iam/v3.0/users/36457840     The following properties can be updated to HR Core: Property Description Corresponds with HR Core field businessEmailAddress Business email address   Example: [email protected] E-mail adres (zakelijk) (NL) Email address (business) (ENG)   Elementnumber: 7212   privateEmailAddress Personal email address of employee   Example: [email protected] E-mail adres (privé) (NL) Email address (private) (ENG)   Elementnumber: 7213   changeDate (new per 17-10-2025) The change in the PATCH will start from this date on forward. The date is the change date of the email addresses (business or private) which are in the body of the PATCH request. When changeDate is not part of the patch, the current date is used.   Reference date in HR Core   Using the changeDate: With the use of changeDate, a business or private email address can be added to HR Core before the employee gets in service.  The changeDate implies the date when the change of business or private email address is active in HR Core If the startDateLogin (see GET) is in the future, use this date as changeDate If the startDateLogin (see GET) has passed and the hireDate has not passed, use today as changeDate If the hireDate (see GET) has passed, use the hireDate (or any later date) as changeDate   Request body example:  { "businessEmailAddress": "[email protected]", "privateEmailAddress": "[email protected]", "changeDate": "2025-10-20" } Returns a 200 when successful   Notes with v3: Compared to v2 the id property can not be patched anymore. This is due to the changed functionality in HR Core. See release note HR Core.  Compared to v2, the employeeCode is no longer supported as a filter.   User (v2) - deprecated The user endpoint supports the retrieval (GET) and update (PATCH) of user related data from HR Core. Base URL of user endpoint:   https://api.youserve.nl/iam/v2.0/users   GET Allows retrieving user related data from HR Core of a single employee. Data can be retrieved using several parameters: personcode or mutkey of the employee (getById).   PersonCode https://api.youserve.nl/iam/v2.0/users?personcode=[personcode]  The personcode matches the personcode in the endpoints Employees and Employments Example: https://api.youserve.nl/iam/v2.0/users?personcode=1012    getById https://api.youserve.nl/iam/v2.0/users/[id]  The id matches the mutkey of the employee which can be found in the endpoint Employees (employees.id) Example: https://api.youserve.nl/iam/v2.0/users/36457840    EmployeeCode (Deprecated) https://api.youserve.nl/iam/v2.0/users?employeecode=[employeeCode]  The employeecode matches the employeecode in the endpoints Employees and Employments. Example: https://api.youserve.nl/iam/v2.0/users?employeecode=1012  Note: the employeecode is only useful if this code is unique for your company. To be sure, use either the getById or PersonCode.   Datamapping Property Description Corresponds with HR Core field id User id of the employee used in the Youforce authentication system   Example:  c7e230db-2a7f-4ef0-ad1d-9d30e7d94a2f   Toegekende identiteit (before: PING Identiteit) (NL) Assigned identity (before: PING Identity) (ENG)   Elementnumber: 10523564         sourceId Username of the user in the Youforce portal.    Example: XX123456   Gebruikersnaam (NL) User name (ENG)   Elementnumber: 61   identityId External Identity in the customer authentication system (IDP) that takes care of authentication   Example: [email protected]   Identity (NL) Identity (ENG)   Elementnumber: 7013     businessEmailAddress Business email address   Example: [email protected]     E-mail adres (zakelijk) (NL) Email address (business) (ENG)   Elementnumber: 7212   privateEmailAddress Personal email address of employee   Example: [email protected]   E-mail adres (privé) (NL) Email address (private) (ENG)   Elementnumber: 7213       PATCH Allows to update user related data in HR Core. Use the personcode, employeecode or mutkey of the employee to update the data:   Examples: https://api.youserve.nl/iam/v2.0/users?personcode=1012  or https://api.youserve.nl/iam/v2.0/users/36457840   or https://api.youserve.nl/iam/v2.0/users?employeecode=1012 (deprecated, employeecode can not be unique)   The following properties can be updated to HR Core: Property Description Corresponds with HR Core field id External Identity in the customer authentication system (IDP) that takes care of authentication. This Identity can be synchronized to  the old Youforce IAM system. In that case, the Identity can be used as with can be used for SSO pupose.    Example: [email protected]   Identity (NL) Identity (ENG)   Elementnumber: 7013 businessEmailAddress Business email address   Example: [email protected] E-mail adres (zakelijk) (NL) Email address (business) (ENG)   Elementnumber: 7212 privateEmailAddress Personal email address of employee   Example: [email protected] E-mail adres (privé) (NL) Email address (private) (ENG)   Elementnumber: 7213   Request body example:  { "id": "[email protected]", "businessEmailAddress": "[email protected]", "privateEmailAddress": "[email protected]" } Returns a 200 when successful     --- User (v1) - deprecated Version 1 of the user endpoint is deprecated. The documentation is available in a separate article: IAM User endpoint.   Workflow GET Workflow The GET Workflow allows clients to retrieve deep-linking URLs for Start Menu tabs and workflows available to employees within HR Self Service. This eliminates the need for users to log in first to My YouServe or Self Service directly. For example, if you want to launch the Employer statement workflow (Dutch: Werkgeversverklaring) from outside Self Service, this endpoint provides the necessary URL. When an employee follows (clicks) the URL, on for example: Employer statement, the workflow will be initiated in Self Service. The employee can then complete the Employer statement form and, upon submission, is redirected back to the external page.   Functional Details Request Parameters - To retrieve a list of available "Start items," the request must include either the employee code or employee number. User Scope - This endpoint is intended for employees only. Requests for managers or professionals are not supported. Response Structure - For a given employee, the endpoint returns: A list of workflow groups (also known as tabs) Each group contains workflows that the employee can initiate Each workflow group includes a deep-linking URL to launch the tab Each individual workflow includes a deep-linking URL to start the workflow directly Language Support - The endpoint supports multiple languages, provided that multilingual configuration is enabled in HR Self Service.   Technical details You can apply a workflow name filter to retrieve only the specified workflow. The calls below will get an OData response with all workflows that an employee can start grouped by Tab Name.    By Employee Code GET https://api.youserve.nl/iam/v1.0/workflow?$expand=workflows($expand=contract)&$count=true&$filter=workflows/any(c: c/contract/employeeCode eq '{employeeCode}') Example: https://api.youserve.nl/iam/v1.0/workflow?$expand=workflows($expand=contract)&$count=true&$filter=workflows/any(c: c/contract/employeeCode eq '952402') The employeecode is the employeeCode property of the Employees.Employments endpoint.   By Employee Number GET https://api.youserve.nl/iam/v1.0/workflow?$expand=workflows($expand=contract)&$count=true&$filter=workflows/any(c: c/contract/employeeNumber eq {employeeNumber}) Example: https://api.youserve.nl/iam/v1.0/workflow?$expand=workflows($expand=contract)&$count=true&$filter=workflows/any(c: c/contract/employeeNumber eq 34720188) The employeeNumber is the MutKey of the employee. This is the id property of the Employees endpoint.   Notice: Employee code is considered as string while employee number is filtered as a number.   Data mapping Property Field Description Example Workflow Dto Id HR Self Service internal ID   Roletype Dto   Enumeration. Hard-coded: Employee Employee UserEmployment Dto Employee Number Employee mutkey (ID)   10459096   Employee Code Employee code   01176   Name Names of all the available workflows F.i. Werkgeversverklaring WorkflowGroup Dto Name All tabs in HR Self Service Start Menu F.i. Verlof, Expenses, Contract   URL Direct link to open a Workflow     URL Direct link to open the tab     Contract number Default always ‘1’ 1 Dto - Data Transfer Object         ... Näytä lisää

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

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