Knowledge base YouServe API's

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 is a Client Application that can list/download/delete the files of authorized business types and authorized tenants.

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

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

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

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

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

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

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

 

 

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   

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

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