Zoeken
Mijn Communities
Help

Onboarding API - Endpoints

15-04-2024 16:59 (Bijgewerkt op 15-04-2024)
  • 0 Antwoorden
  • 0 kudos
  • 390 Weergaven

 

Endpoints

Companies

The entity Companies contains data related to the existing sub-companies within a tenant/client.
https://api.youserve.nl/onboarding/companies 

 

Filters

Single company - Retrieve specific company by adding the id of the company.

GET https://api.youserve.nl/onboarding/companies/<id>

 

Companycode - Retrieve specific company by filtering on companycode.

https://api.youserve.nl/onboarding/companies?companyCode=<companyCode>

 

Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request. 

By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range.

https://api.youserve.nl/onboarding/companies?ChangedAfter=2024-01-01T10:00:00.000Z&ChangedUntil=2024-06-01T11:00:00.000Z.  

Format: YYYY-MM-DDTHH:MM:SS.sssZ.

 

 

Data mapping

PI field

Description

Example

HR Core Business (r1)

Id

Technical and unique Id for a company. The Id is unique within the entity and tenant. The Id is generated by the system and can not be changed by a user.
35146808

mutKey of company

code

Code of company

500

Company code

NL: Bedrijfscode

name

Name of the company

Icommus

Company name

NL: Bedrijfsnaam

totalWorkAmount

Indicates the full-time hours per period within a specific company. For example 40 or 36 hours per week.

40

Hours period

NL: Uren periode

Element nr: 465
establishmentCountry

Country of company

NL

Country of establishment

NL: Vestigingsland bedrijf

Element nr: 10525700
address: street

Street of company
Icommuslaan

Street

NL: Straat

Element nr: 29
address: houseNumber

house number of company
500

House number

NL: Huisnummer

Element nr: 30
address: houseNumberAddition

addition to house number of company
a

House number addition

NL: Huisnummer toevoeging

Element nr: 31
address: postalCode

postal code of company
5050 IC

Postal code

NL: Postcode

Element nr: 32
address: city

city of company
Amsterdam

Municipality

NL: Woonplaats

Element nr: 33
address: country

 
 

 
mailingAddress: boxnumber
  boxnumber of company  6060

P.O. box

NL: Postbus

Element nr:  446
mailingAddress: postalCode
 Post code of boxnumber of company 6060 AB

Post code P.O. box address

NL: Postcode postbusadres

Element nr: 447
mailingAddress: cityTown

city of boxnumber of company

Amsterdam

Town P.O. box address

NL: 
Woonplaats postbusadres

Element nr: 448

validFrom

Startdate of the timeslice/version of a record.

2024-01-01

Referencedate

NL: Peildatum

validUntil

Enddate of the timeslice/version of a record.
The enddate is the (validFrom-1) of the successive version. If no successive version is available then value is 9999-12-31.

9999-12-31
2024-12-31

 N/A
isDeleted

Provide the active/inactive status of the record in the core system.

false

 N/A

Extensions are not supported in companies endpoint.

 

 

Data mapping

Fields marked with (V) should be connected with the results of the endpoint ‘Valuelists’.

Employees

This endpoint will return unique persons with their associated contracts. 

Only the current active version of the person with its contracts is returned.

If person has only contracts in the future, this will be returned.

If person only has active contract in the past, the last contract is returned.
Details we’ll expose are personal details, partner details, contact information, and the latest address details. 

 

To fetch the list of all employees (persons with contracts) within a tenant the Employee endpoint can be used without using any additional parameters.

https://api.youserve.nl/onboarding/employees 

 

Filters

PersonId/ PersonCode - In case specific person incl. contract records are needed, this can be retrieved based on the “personId” or “personCode”.

https://api.youserve.nl/onboarding/employees/<personId> 
https://api.youserve.nl/onboarding/employees?personCode=<personCode> 

 

When person layer is enabled in HRCore Business, the PersonId is equal to PersonCode. If so, personId can also be used in filtering:

https://api.youserve.nl/onboarding/employees?personCode=<personId> 

 

Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request. 

https://api.youserve.nl/onboarding/employees?ChangedAfter=2024-01-01T10:00:00.000Z&ChangedUntil=2024-06-01T11:00:00.000Z. Format: YYYY-MM-DDTHH:MM:SS.sssZ.

 

Data mapping

Employee

API field

Description

Example

HR Core Business (r1)

id

The Id of a unique person within a tenant.

10056832

10519680 - personNumber

personCode

The logical person code of the employee.

4005614

7014 - Uniek Persoonlijk ID (UPI)

isDeleted

Provide the active/inactive status of the Person in the core system.

False

 

initials

The initials of the employee. Format depends.

A.M.

 25 - Voorletters

firstNames

The official given names of the employee as stored in the HR Core system.

Anne Marie

 51 - Voornamen

knownAs

The name is used by the employee as his first name.

Amy

 165 - Roepnaam

lastName

The last which is currently used by the employee as his last name.

Vries - Van Eijck

 524 - Opgemaakte naam aanhef

gender (V)

Gender of the person conform the ISO/IEC 5128 standard

(0) Not known
(1) Male
(2) Female
(9) Not applicable

2

P00330 - Geslacht
M = Man / Male
V = Vrouw / Female

emailAddresses

private email address

AnneMarie@privatemail.com

Prive: 7213 - E-mailadres Prive

validFrom

Startdate of the timeslice/version of a record.

2024-01-01

Reference date / Peildatum (NL)

validUntill

Enddate of the timeslice/version of a record.
The enddate is the (validFrom-1) of the successive version. If no successive version is available then value is 9999-12-31.

9999-12-31
2024-12-31

 

 

Contracts

API field

Description

Example

HR Core Business (r1)

Id

Technical and unique Id for a contract. The Id is unique within the entity and tenant. The Id is generated by the system and can not be changed by a user.

23456789

49 - Mutkey of the contract

validFrom

Startdate of the timeslice/version of a record.

2024-01-01

Reference date / Peildatum (NL)

validUntill

Enddate of the timeslice/version of a record.
The enddate is the (validFrom-1) of the successive version. If no successive version is available then value is 9999-12-31.

9999-12-31

2024-12-31

 

isDeleted

Provide the active/inactive status of the Contract in the core system.

False

 

personId

The Id of a unique person within a tenant.

10056832

10519680 - personNumber

employeeCode

Logical code of the employee or employment (reference).

01

22 - Medewerkercode

companyId

Unique (numeric) identifier of the company
11058330

mutkey of company

originalHireDate

The first hire date of original hire date of an employee within the organization. This date is important for the tenure or working anniversary of an employee.

2010-10-01

308 - Datum indienst organisatie

dischargeDate

The end date/discharge date of the employment. This is always an ‘up to and including’ date. The field will always be in the response, even if the field is not filled.

2025-12-31

10520479 - Geplande laatste datum indienst

employmentType (V)

Type of employment like Internal Employee, Contractor, Wachtgelder

shortName: Code or short name of the employment type
fullName: name or full title of the employment type

CNTR

7393 - Type Medewerker

jobProfile

Official job title or job profile of the employment. The Job profile contains the following details: shortName > Code or short name of the job profile.

DEV

97 - Functie

organizationUnit

Official organization unit of employment. The Organization Unit contains the following details: reference Id to the OrgUnit.
ShortName: Code or short name of the organization Unit

PD

6000 - Organisatorische eenheid

emailAddresses: type

type

 

  

emailAddresses: address

business email address

AnneMarie@work.com

Business : 7212 - E-mailadres
extensions: key

Extra customer specific data can be added with extensions.
extensions: value

 

Jobprofiles

This endpoint returns all the relevant data regarding the job profiles, like Job family information & Job profile descriptions.

https://api.youserve.nl/onboarding/jobprofiles


JobProfiles can be configured on different levels in the core system, on ‘client level’ or on 'company level'. The endpoint will provide details regarding the the level.

In case a JobProfile belongs to a specific subcompany of a client, the response will also show the corresponding “companyCode”. (Dutch: "Functie informatie")

 

Output example 1 : JobProfile on client (tenant) level

{
 "validFrom": "2024-01-01",
 "validUntil": "9999-12-31"
 "extensions": [],
 "id": "45",
 "fullName": "Functie 45",
 "level": "client",
 "isDeleted": false
 }

Output example 2 : JobProfile on company level

{
 "validFrom": "2024-01-01",
 "validUntil": "9999-12-31"
 "extensions": [],
 "id": "185",
 "fullName": "Functie 185",
 "level": "company",
 "companyCode" : "3511"
 "isDeleted": false
 }

 

 

Filters

Single job profile - Retrieve 1 jobProfile by adding the id of the jobprofile.

https://api.youserve.nl/onboarding/jobprofiles/<id>  

 

Level - Filter out specific Job Profiles corresponding to a specific “level”.

https://api.youserve.nl/onboarding/jobprofiles?level=client

 

Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request. By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range.

https://api.youserve.nl/onboarding/jobprofiles?ChangedAfter=2024-01-01T10:00:00.000Z&ChangedUntil=2024-06-01T11:00:00.000Z. Format: YYYY-MM-DDTHH:MM:SS.sssZ.

 

 

Data mapping

Fields marked with (V) should be connected with the results of the endpoint ‘Valuelists’.

API field

Description

Example

HR Core Business (r1)

id

 

123

Mutkey of jobprofile 4

fullName

The full name of the Job Profile.

Developer02

97 - DEVV. FLDDES

level

Indicates the level in the core system where the job profile is configured (“client” level or “company” level).

Client

Company

 

companyCode

In case the level is indicated as “company”, the API expose also the corresponding “companyCode”. In case the Job Profile is configured at “client” level, the value of this field is “NULL” and will not be shown in the API response.

50320014

 

isDeleted

Provide the active/inactive status of the record in the core system.

False

 

validFrom

Startdate of the timeslice/version of a record.

2024-01-01

Reference date / Peildatum (NL)

validUntil

Enddate of the timeslice/version of a record. The enddate is the (validFrom-1) of the successive version. If no successive version is available then value is 9999-12-31.

9999-12-31

9999-12-31
2024-12-31

Extensions are not supported in this endpoint.

 

 

Organization Units

This endpoint will provide organization Units 

(HRCore Business: "Instellingen > Formatie en Organisatie > Organisatorische eenheden")) 

https://api.youserve.nl/onboarding/organizationunits

 

Filters

Single organisation unit - Retrieve specific org unit by adding the id of the org unit.

https://api.youserve.nl/onboarding/organizationunits/<id>  

 

Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request. By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range.

https://api.youserve.nl/onboarding/organizationunits?ChangedAfter=2024-01-01T10:00:00.000Z&ChangedUntil=2024-06-01T11:00:00.000Z. Format: YYYY-MM-DDTHH:MM:SS.sssZ.

 

Data mapping

Fields marked with (V) should be connected with the results of the endpoint ‘Valuelists’.

API field

Description

Example

HR Core Business (r1)

Id

Technical and unique id of the organization Unit. the Id is unique within the entity and tenant. The id is generated by the system and can not be changed by a user.

12009338

6000 - Key org unit

shortName

Code or short name of the organizational unit.

SAL_NL

548 - Code OE

fullName

Name of the organization unit.

Sales Netherlands

549 - Naam OE

parentOrgUnit

Code of the parent organization unit

SALES_EU

6000 - Organisatie eenheid

Is the reference to the logical code

isDeleted

Provide the active/inactive status of the Org Unit in the core system.

 

 

organizationUnitType (V)

Code for the organization unit type.

BU

7475 - Type organisatie

manager

Manager of the Organisation Unit.

4005614

7137 - Manager

(mutkey of employee)
managerPersonId

The globally unique id assigned to an the management employee

12345678

10519680 - Persoon nummer

Corresponds with:

Endpoint: Person,

Property: personCode
backupManager

backup manager of org unit

4005614

7011 - Backup manager
(mutkey of employee)
backupManagerPersonId PersonCode of the Backup manager of the Organization Unit.

12345678

10519680 - Persoon nummer

Corresponds with:

Endpoint: Person,

Property: personCode

validFrom

Startdate of the timeslice/version of a record.

2024-01-01

 Reference date / Peildatum (NL)

validUntil

Enddate of the timeslice/version of a record.
The enddate is the (validFrom-1) of the successive version. If no successive version is available then value is 9999-12-31.

9999-12-31
2024-12-31

  

Extensions are not supported in this endpoint.

 

 

Role Assignments

The Role assignments endpoint delivers the role an employee has in the organization. 

https://api.youserve.nl/onboarding/roleassignments

 

Filters

Single roleassignment - Retrieve 1 role assignments by adding the id of the item.

https://api.youserve.nl/onboarding/roleassignments/<id>

 

OrganizationUnitId - Retrieve all roleassignments for 1 specific organizational unit:

https://api.youserve.nl/onboarding/roleassignments?organizationUnitId=<organizationUnitId>

 

Incremental load - To retrieve only changes after last request, use the ChangedAfter and ChangedUntil in the request. By executing the parameters ChangedAfter - ChangedUntil you will only the changed records within this time range.

https://api.youserve.nl/onboarding/roleassignments?ChangedAfter=2024-01-01T10:00:00.000Z&ChangedUntil=2024-06-01T11:00:00.000Z. Format: YYYY-MM-DDTHH:MM:SS.sssZ.

 

Data mapping

Fields marked with (V) should be connected with the results of the endpoint ‘Valuelists’.

API field

Description

Example

HR Core Business (r1)

Id

The id of the role Code or the role assignment

658332

960 - Key of the role assignment

organizationUnitId

The Id of the Organization Unit where this Role Assignment belongs to.

12345

548 - Code of the Organisation Unit
Key of the Organisation Unit. Referring to: organizationunits.id

shortName

The shortname of the role 

DM1

549 - (short)name of the role assignment

fullName

The fullname of the role 

 

 

personId

The Id of a unique person within a tenant.

10056832

10519680 - personNumber

Referring to: Persons.id

employeeId

Technical number for an employee

12345

mutkey of employee

includingChildOrgUnits

Refers to the level of authorisation of a specific role within an organisation.

true / false

913 - includeChildOU

startDate

Start date of the role assignment

2020-01-01

  

endDate

End date of the role assignment

9999-12-31

  
isDeleted

Provide the active/inactive status of the record in the core system.

false

 N/A

Extensions are not supported in this endpoint.

 

Value lists

This endpoint returns all the corresponding code & descriptions of pairs of fields that are available in the Medical Leave API.

 

This reference lists endpoint supports filtering based on type. For example, the property “Gender” will be returned as a value 1 or 2, and based on the value list data the user is able to define that 1 = male & 2 = female.

Other examples : “finalResult”; “contractType”; “country”; “employmentType”; “gender”; “nameAssembleOrder”; “organisationUnitType”; “sicknessType” & “workingUnit”. 

 

In ‘Data Mapping’, the fields, which are marked with (V), these fields should be connected with the results of the endpoint ‘Valuelists’.

Valuelists can be configured on different levels in the core system, on ‘client level’ or on ‘company level'. On top is these levels there are also 'system level’ Valuelists.

 

Output example 1 : Valuelists on (core) system level

{
 "validFrom": "2011-01-01",
 "validUntil": "9999-12-31"
 "shortName": "1",
 "fullName": "Man",
 "type": "gender",
 "level": "System",
 "isDeleted": false,
 },

Output example 2 : Valuelists on client (tenant) level

{
 "validFrom": "2018-08-10",
 "validUntil": "9999-12-31"
 "shortName": "2",
 "fullName": "Stagiair",
 "type": "employmentType",
 "level": "Client",
 "isDeleted": false,
 },

 

Retrieve all valuelists:

https://api.youserve.nl/onboarding/valuelists 

 

Filters

Single type - Retrieve details of a specific type of valuelist, based on the “type”.

https://api.youserve.nl/onboarding/valuelists/<type>

example https://api.youserve.nl/onboarding/valuelists/employmentType

 

Level - Filter out specific valuelists corresponding to a specific “level”.

https://api.youserve.nl/onboarding/valuelists?level=company 

 

Combination level, type - combining the 2 above filters.

https://api.youserve.nl/onboarding/valuelists/function?level=company 

 

 

 

0 Kudos
Medewerkers

Visma Community

Gebruiksvoorwaarden

Richtlijnen

Veelgestelde vragen

Informatie over cookies

Over Visma

Dit is Visma

Volg Visma

Blog

LinkedIn

YouServe

Website

Contact

Inloggen applicaties

Visma

Copyright 2022 Visma Community. All right reserved.

Choose your region:
Choose your Region
Go