Search
Turn on suggestions
Auto-suggest helps you quickly narrow down your search results by suggesting possible matches as you type.
Sign In
My Products
Help
Sign in or create account
to get a personalized navigation.
Sign in or create account
to get a personalized navigation.
User Profile
Carmen Martínez
14
Posts
0
Kudos
0
Solutions
28-02-2025
15:39
1 Kudo
2025-06-05 - Start workflows
Now it is possible to start workflows in HRSS using the HRPAPI and check the status.
2025-02-28 - Added new fields
The employee and contract data endpoints are extended with new fields:
Employee: Identity 7013 UPI 7014 OwnNameCode 28
Contract: Classification 474 SalaryScale 10300574 EmploymentType 7393 LastWorkingDate 10520479 CLACode 47
... View more
23-01-2025
19:03
2025-01-23 - Dispatcher improvement
For employees with a large amount of versions that cannot be stored, the solution is to remove the older versions until it fits in the storage structure.
... View more
Labels:
24-06-2024
20:20
2024-06-24 - API enhancements
The following enhancements are now available:
Extend candidate model with 30 custom fields
CustomFields are string.
Allow up to 100Mb for the whole request
... View more
Labels:
10-10-2023
12:17
Swagger documentation
The following swagger page gives an overview of the endpoints:
HR Core and Payroll API
Endpoints
Addresses
These endpoints return the address data of the employee that consists of the home and postal address. Each field has its own timeline.
Get the addresses of all employees of a customer:
- Get: https://api.youserve.nl/hrp/v1.0/addresses
Get the addresses of all employees of a company:
- Get: https://api.youserve.nl/hrp/v1.0/addresses?companyId=10028636
Get the addresses of an employee:
- Get: https://api.youserve.nl/hrp/v1.0/employees/10030024/addresses
Response example:
{
"employeeId": 10030024,
"companyId": 10028636,
"personCode": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "9999-12-31T00:00:00+00:00",
"value": "NU1926"
}
],
"employeeCode": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "120"
}
],
"initials": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "2022-01-31T00:00:00Z",
"value": "A.H."
},
{
"startDate": "2022-02-01T00:00:00Z",
"endDate": "2023-03-05T00:00:00Z",
"value": "A.H.T."
},
{
"startDate": "2023-03-06T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "AB"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "AFR"
}
],
"lastName": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Huffman"
}
],
"addresses": [
{
"type": "Home",
"country": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "2006-10-31T00:00:00Z",
"value": "NL"
},
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "NL"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "NL"
}
],
"street": [
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2019-04-07T00:00:00Z",
"value": "Dobberhof"
},
{
"startDate": "2019-04-08T00:00:00Z",
"endDate": "2019-04-19T00:00:00Z",
"value": "zevenhuizen"
},
{
"startDate": "2019-04-20T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "biltstraat"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "wigsfrfvpb"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Vitoria"
}
],
"houseNumber": [
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2021-07-31T00:00:00Z",
"value": "5"
},
{
"startDate": "2021-08-01T00:00:00Z",
"endDate": "2022-02-28T00:00:00Z",
"value": "5"
},
{
"startDate": "2022-03-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "5"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "17"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "2"
}
],
"houseNumberAddition": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "25"
}
],
"postalCode": [
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "1121 PB"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "1234 AB"
}
],
"municipality": [
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2014-07-31T00:00:00Z",
"value": "Deventer"
},
{
"startDate": "2014-08-01T00:00:00Z",
"endDate": "2022-01-31T00:00:00Z",
"value": "Deventer"
},
{
"startDate": "2022-02-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "Deventer"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "kkvviybree"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Madrid"
}
],
"location": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "guufgvstcy"
}
],
"region": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "xhcvjoprbh"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Sanfer"
}
]
},
{
"type": "Postal",
"country": [
{
"startDate": "2017-07-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "NL"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "NL"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "NL"
}
],
"street": [
{
"startDate": "2017-07-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "Plotterweg"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "golurxcftu"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Vitoria2"
}
],
"houseNumber": [
{
"startDate": "2017-07-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "A"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "06"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "03"
}
],
"houseNumberAddition": [],
"postalCode": [
{
"startDate": "2017-07-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "3821 BB"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "1234 AB"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "4567 CD"
}
],
"municipality": [
{
"startDate": "2017-07-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "Amerfoort"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "ponccrykpq"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "arturo2"
}
],
"location": [
{
"startDate": "2017-07-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "hier"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "xhfjpfbkmu"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "arturo3"
}
],
"region": [
{
"startDate": "2017-07-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "werk"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "cndsqcxmkt"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "arturo4"
}
]
}
]
}
This endpoint allows to update an employee's addresses. The request body is fixed and the missing fields are ignored. The start date is mandatory.
- Patch: https://api.youserve.nl/hrp/v1.0/addresses/10030024
Request body example:
{
"StartDate": "2023-04-03",
"Addresses": [
{
"Type": "Home",
"Street": "Straat",
"HouseNumber": "1",
"Municipality": "Municipality",
"Region": "Amsterdam"
},
{
"Type": "Postal",
"Street": "Tejas",
"HouseNumber": "1",
"Municipality": "San Fernando",
"Region": "Madrid"
}
]
}
As it is an asynchronous operation, you will get a requestId to check using the Get request status endpoint.
{
"requestId": "4385028f-e8b2-4503-9b94-4b0ae6aaa653"
}
Bank Accounts
These endpoints return the bank account data of the employees that consists of 10 bank accounts. Each field has its own timeline.
Get the bank accounts of all employees of a customer:
- Get: https://api.youserve.nl/hrp/v1.0/bankAccounts
Get the bank accounts of all employees of a company:
- Get: https://api.youserve.nl/hrp/v1.0/bankAccounts?companyId=10028636
Get the bank accounts of an employee:
- Get: https://api.youserve.nl/hrp/v1.0/employees/10030024/bankAccounts
Response example:
{
"employeeId": 10030024,
"companyId": 10028636,
"personCode": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "9999-12-31T00:00:00+00:00",
"value": "NU1926"
}
],
"employeeCode": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "120"
}
],
"initials": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "2022-01-31T00:00:00Z",
"value": "A.H."
},
{
"startDate": "2022-02-01T00:00:00Z",
"endDate": "2023-03-05T00:00:00Z",
"value": "A.H.T."
},
{
"startDate": "2023-03-06T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "AB"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "AFR"
}
],
"lastName": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Huffman"
}
],
"bankAccounts": [
{
"id": 1,
"iban": [
{
"startDate": "2012-10-01T00:00:00Z",
"endDate": "2013-01-31T00:00:00Z",
"value": "NL50INGB0000009887"
},
{
"startDate": "2013-02-01T00:00:00Z",
"endDate": "2013-08-31T00:00:00Z",
"value": "NL50INGB0000009887"
},
{
"startDate": "2013-09-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "NL50INGB0000009887"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "GB33BUKB20201555555555"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "GB33BUKB20201555555555"
}
],
"bic": [
{
"startDate": "2012-10-01T00:00:00Z",
"endDate": "2013-01-31T00:00:00Z",
"value": "INGBNL2A"
},
{
"startDate": "2013-02-01T00:00:00Z",
"endDate": "2013-08-31T00:00:00Z",
"value": "INGBNL2A"
},
{
"startDate": "2013-09-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "INGBNL2A"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "MOLUNL22"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "MOLUNL22"
}
],
"description": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "tksapvnxfq"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "NewDescription"
}
],
"accountType": [
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "01"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "01"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "01"
}
],
"accountHolder": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "stppb"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "arthur"
}
],
"amount": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "100,5"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "100"
}
]
},
{
"id": 2,
"iban": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "GB33BUKB20201555555555"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "GB33BUKB20201555555555"
}
],
"bic": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "MOLUNL22"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "MOLUNL22"
}
],
"description": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "wxrhuivevj"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "NewDescription2"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "test5"
}
],
"accountType": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "01"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "01"
}
],
"accountHolder": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "nqvmq"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "arthur"
}
],
"amount": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "100,5"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "4"
}
]
},
{
"id": 3,
"iban": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "GB33BUKB20201555555555"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "GB33BUKB20201555555555"
}
],
"bic": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "MOLUNL22"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "MOLUNL22"
}
],
"description": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "jipeavrepm"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "test5"
}
],
"accountType": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "01"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "01"
}
],
"accountHolder": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "nnfkk"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "arthur"
}
],
"amount": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "100,5"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "3"
}
]
},
{
"id": 4,
"iban": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "GB33BUKB20201555555555"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "GB33BUKB20201555555555"
}
],
"bic": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "MOLUNL22"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "MOLUNL22"
}
],
"description": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "wnwifysqin"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "test5"
}
],
"accountType": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "01"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "01"
}
],
"accountHolder": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "gcimf"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "arthur"
}
],
"amount": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "100,5"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "2"
}
]
},
{
"id": 5,
"iban": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "GB33BUKB20201555555555"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "GB33BUKB20201555555555"
}
],
"bic": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "MOLUNL22"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "MOLUNL22"
}
],
"description": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "rkqdbeusep"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "test5"
}
],
"accountType": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "01"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "01"
}
],
"accountHolder": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "ckocx"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "arthur"
}
],
"amount": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-04-02T00:00:00Z",
"value": "100,5"
},
{
"startDate": "2023-04-03T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "1"
}
]
}
]
}
This endpoint allows to update an employee's bank accounts. The request body is fixed and the missing fields are ignored. The start date is mandatory.
- Patch: https://api.youserve.nl/hrp/v1.0/bankAccounts/10030024
Request body example:
{
"StartDate": "2023-04-03",
"BankAccounts": [
{
"Id": 1,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "tksapvnxfq",
"AccountType": "01",
"AccountHolder": "stppb",
"Amount": "100,5"
},
{
"Id": 2,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "wxrhuivevj",
"AccountType": "01",
"AccountHolder": "nqvmq",
"Amount": "100,5"
},
{
"Id": 3,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "jipeavrepm",
"AccountType": "01",
"AccountHolder": "nnfkk",
"Amount": "100,5"
},
{
"Id": 4,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "wnwifysqin",
"AccountType": "01",
"AccountHolder": "gcimf",
"Amount": "100,5"
},
{
"Id": 5,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "rkqdbeusep",
"AccountType": "01",
"AccountHolder": "ckocx",
"Amount": "100,5"
}
]
}
As it is an asynchronous operation, you will get a requestId to check using the Get request status endpoint.
{
"requestId": "72d2bd02-517e-425e-9593-cc2f631b09aa"
}
Personal Details
These endpoints return the personal details of the employee. Each field has its own timeline.
Get the personal details of all employees of a customer:
- Get: https://api.youserve.nl/hrp/v1.0/personalDetails
Get the personal details of all employees of a company:
- Get: https://api.youserve.nl/hrp/v1.0/personalDetails?companyId=10028636
Get the personal details of an employee:
- Get: https://api.youserve.nl/hrp/v1.0/employees/10030024/personalDetails
Response example:
{
"employeeId": 10030024,
"companyId": 10028636,
"personCode": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "9999-12-31T00:00:00+00:00",
"value": "NU1926"
}
],
"employeeCode": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "120"
}
],
"initials": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "2022-01-31T00:00:00Z",
"value": "A.H."
},
{
"startDate": "2022-02-01T00:00:00Z",
"endDate": "2023-03-05T00:00:00Z",
"value": "A.H.T."
},
{
"startDate": "2023-03-06T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "AB"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "AFR"
}
],
"firstNames": [
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2023-01-31T00:00:00Z",
"value": "Arno Hendrik"
},
{
"startDate": "2023-02-01T00:00:00Z",
"endDate": "2023-03-05T00:00:00Z",
"value": "Joshua Megan"
},
{
"startDate": "2023-03-06T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Juan_1"
}
],
"knownAs": [
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2023-03-04T00:00:00Z",
"value": "Arno"
},
{
"startDate": "2023-03-05T00:00:00Z",
"endDate": "2023-03-05T00:00:00Z",
"value": "1"
},
{
"startDate": "2023-03-06T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "Juan_1"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Peter"
}
],
"lastName": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Huffman"
}
],
"lastNamePrefix": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "de"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "ak"
}
],
"maritalStatus": [
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "1"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "1"
}
],
"partnerName": [
{
"startDate": "2017-07-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "Heek"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "hlplocatnw"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Lola"
}
],
"partnerNamePrefix": [
{
"startDate": "2017-07-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "van"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "nf"
}
],
"titlePrefix": [
{
"startDate": "2023-03-05T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "1"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "rm"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Mr"
}
],
"titleSuffix": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "k"
}
],
"gender": [
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2013-05-31T00:00:00Z",
"value": "1"
},
{
"startDate": "2013-06-01T00:00:00Z",
"endDate": "2014-07-31T00:00:00Z",
"value": "1"
},
{
"startDate": "2014-08-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "1"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "1"
}
],
"birthDate": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "1962-11-08"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "2010-03-05"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "1979-03-23"
}
],
"birthplace": [],
"nationality": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "2006-10-31T00:00:00Z",
"value": "0001"
},
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "0001"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "0001"
}
],
"dateOfDeath": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "2023-03-08"
}
],
"userUID": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "FakePingId"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "046588"
}
],
"communicationLanguage": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "2006-10-31T00:00:00Z",
"value": "NL"
},
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2013-08-31T00:00:00Z",
"value": "NL"
},
{
"startDate": "2013-09-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "NL"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "NL"
}
],
"bsnSocSecNumber": [
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2023-03-26T00:00:00Z",
"value": "111222333"
},
{
"startDate": "2023-03-27T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "283232237"
}
],
"phoneNumbers": [
{
"type": "Mobile",
"number": [
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "06-11987622"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "085282265"
}
]
},
{
"type": "Mobile",
"number": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "532186503"
}
]
}
],
"emailAddresses": [
{
"type": "Work",
"email": [
{
"startDate": "2006-11-01T00:00:00Z",
"endDate": "2022-02-28T00:00:00Z",
"value": "ah.devoogd@raet.com"
},
{
"startDate": "2022-03-01T00:00:00Z",
"endDate": "2023-03-08T00:00:00Z",
"value": "demo@raet.com"
},
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "test2@visma.com"
}
]
},
{
"type": "Private",
"email": [
{
"startDate": "2023-03-09T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "test@visma.com"
}
]
}
]
}
This endpoint allows to update an employee's personal details. The request body is fixed and the missing fields are ignored. The start date is mandatory.
- Patch: https://api.youserve.nl/hrp/v1.0/personalDetails/10030024
Request body example:
{
"StartDate": "2023-03-09",
"PersonalDetails": {
"EmployeeCode": "AFR26",
"Initials": "AFR",
"FirstNames": "Arturo",
"KnownAs": "Arthur",
"LastName": "Conan",
"LastNamePrefix": "mr",
"MaritalStatus": "1",
"PartnerName": "Alexandra",
"PartnerNamePrefix": "ms",
"TitlePrefix": "Dr",
"TitleSuffix": "jr",
"Gender": "1",
"BirthDate": "1978-03-12",
"Birthplace": "The Netherlands",
"Nationality": "0001",
"DateOfDeath": "",
"UserUID": "046588",
"CommunicationLanguage": "NL",
"PhoneNumbers": [
{
"Type": "Mobile",
"Number": "639424977"
},
{
"Type": "Private",
"Number": "912801078"
}
],
"EmailAddresses": [
{
"Type": "Private",
"Email": "arthur@gmail.com"
},
{
"Type": "Work",
"Email": "arturo.conan@visma.com"
}
]
}
}
As it is an asynchronous operation, you will get a requestId to check using the Get request status endpoint.
{
"requestId": "50b00afd-e9f2-44b1-bc10-c2a3132641a7"
}
Employees
These endpoints return the data of the employees: personal details, bank accounts, addresses. Each field has its own timeline.
Get all employees of a customer:
- Get: https://api.youserve.nl/hrp/v1.0/employees
Get all employees of a company:
- Get: https://api.youserve.nl/hrp/v1.0/employees?companyId=10028636
Get the data of an employee:
- Get: https://api.youserve.nl/hrp/v1.0/employees/10030024
Response example:
{
"employeeId": 10030307,
"companyId": 10028637,
"personalDetails": {
"personCode": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "9999-12-31T00:00:00+00:00",
"value": "NU1545"
}
],
"employeeCode": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "10090"
}
],
"initials": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "IH"
}
],
"firstNames": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Inge"
}
],
"knownAs": [],
"lastName": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Rooibos"
}
],
"lastNamePrefix": [],
"maritalStatus": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "1"
}
],
"partnerName": [],
"partnerNamePrefix": [],
"titlePrefix": [],
"titleSuffix": [],
"gender": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "2"
}
],
"birthDate": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "1974-08-09"
}
],
"birthplace": [],
"nationality": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "0001"
}
],
"dateOfDeath": [],
"userUID": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "FakePingId"
}
],
"communicationLanguage": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "NL"
}
],
"bsnSocSecNumber": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "080141729"
}
],
"phoneNumbers": [],
"emailAddresses": []
},
"addresses": [
{
"type": "Home",
"country": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "NL"
}
],
"street": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Dorpstraat"
}
],
"houseNumber": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "12"
}
],
"houseNumberAddition": [],
"postalCode": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "6745 re"
}
],
"municipality": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "2016-06-30T00:00:00Z",
"value": "Oegstgeest"
},
{
"startDate": "2016-07-01T00:00:00Z",
"endDate": "2017-05-31T00:00:00Z",
"value": "Oegstgeest"
},
{
"startDate": "2017-06-01T00:00:00Z",
"endDate": "2023-01-31T00:00:00Z",
"value": "Oegstgeest"
},
{
"startDate": "2023-02-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Oegstgeest"
}
],
"location": [],
"region": []
},
{
"type": "Postal",
"country": [],
"street": [],
"houseNumber": [],
"houseNumberAddition": [],
"postalCode": [],
"municipality": [],
"location": [],
"region": []
}
],
"bankAccounts": [
{
"id": 1,
"iban": [
{
"startDate": "2013-09-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "NL55INGB0000005432"
}
],
"bic": [
{
"startDate": "2013-09-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "INGBNL2A"
}
],
"description": [],
"accountType": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "01"
}
],
"accountHolder": [],
"amount": []
},
{
"id": 2,
"iban": [
{
"startDate": "2013-09-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "NL76INGB0000000689"
}
],
"bic": [
{
"startDate": "2013-09-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "INGBNL2A"
}
],
"description": [],
"accountType": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "06"
}
],
"accountHolder": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Wehkamp"
}
],
"amount": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "200"
}
]
},
{
"id": 4,
"iban": [
{
"startDate": "2013-09-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "NL81INGB0000002345"
}
],
"bic": [
{
"startDate": "2013-09-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "INGBNL2A"
}
],
"description": [],
"accountType": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "03"
}
],
"accountHolder": [],
"amount": []
}
]
}
This endpoint allows to create an employee (Hire). No contract data is needed except for the Collective Labour Agreement that is mandatory. Also it is allowed to send the field "templateGroup" in the contract data and the data of the employee in HR Core will be filled in according with the definition.
- Post: https://api.youserve.nl/hrp/v1.0/employees
Request body example:
{
"companyId": 10028637,
"startDate": "2023-03-29",
"PersonalDetails": {
"EmployeeCode": "YSDU001",
"Initials": "A.",
"FirstNames": "Arthur Ignatius",
"KnownAs": "A2D2",
"LastName": "Conan Doyle",
"LastNamePrefix": " van",
"MaritalStatus": "1",
"PartnerName": "Jean Leckie",
"PartnerNamePrefix": "van",
"TitlePrefix": "Mr.",
"TitleSuffix": "ex",
"Gender": "1",
"BirthDate": "1978/05/22",
"Birthplace": "Spain",
"Nationality": "0001",
"UserUID": "1234567",
"CommunicationLanguage": "NL",
"BsnSocSecNumber": "292985782",
"PhoneNumbers": [
{
"Type": "Mobile",
"Number": "085282265"
},
{
"Type": "Private",
"Number": "532186503"
}
],
"EmailAddresses": [
{
"Type": "Private",
"Email": "test@visma.com"
},
{
"Type": "Work",
"Email": "test2@visma.com"
}
]
},
"Addresses": [
{
"Type": "Home",
"Country": "NL",
"Street": "wigsfrfvpb",
"HouseNumber": "17",
"HouseNumberAddition": "25",
"PostalCode": "1234 AB",
"Municipality": "kkvviybree",
"Location": "guufgvstcy",
"Region": "xhcvjoprbh"
},
{
"Type": "Postal",
"Country": "NL",
"Street": "golurxcftu",
"HouseNumber": "13",
"HouseNumberAddition": "06",
"PostalCode": "1234 AB",
"Municipality": "ponccrykpq",
"Location": "xhfjpfbkmu",
"Region": "cndsqcxmkt"
}
],
"BankAccounts": [
{
"Id": 1,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "tksapvnxfq",
"AccountType": "01",
"AccountHolder": "stppb",
"Amount": "101,5"
},
{
"Id": 2,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "wxrhuivevj",
"AccountType": "01",
"AccountHolder": "nqvmq",
"Amount": "102,5"
},
{
"Id": 3,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "jipeavrepm",
"AccountType": "01",
"AccountHolder": "nnfkk",
"Amount": "103,5"
},
{
"Id": 4,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "wnwifysqin",
"AccountType": "01",
"AccountHolder": "gcimf",
"Amount": "104,5"
},
{
"Id": 5,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "rkqdbeusep",
"AccountType": "01",
"AccountHolder": "ckocx",
"Amount": "105,5"
}
],
"Contract": {
"CollectiveLabourAgreement": "13155437"
}, "templateGroup": "0100"
}
As it is an asynchronous operation, you will get a requestId to check using the Get request status endpoint.
{
"requestId": "d5e5edd9-bdf2-4413-bf53-340982d8f48e"
}
This endpoint allows to update an employee. The request body is fixed and the missing fields are ignored. The start date is mandatory.
- Patch: https://api.youserve.nl/hrp/v1.0/employees/10030024
Request body example:
{
"StartDate": "2023-03-09",
"PersonalDetails": {
"EmployeeCode": "120",
"Initials": "fq",
"FirstNames": "cafkndvcro",
"KnownAs": "yuwlr",
"LastName": "aisejkqi",
"LastNamePrefix": "ak",
"MaritalStatus": "1",
"PartnerName": "hlplocatnw",
"PartnerNamePrefix": "nf",
"TitlePrefix": "rm",
"TitleSuffix": "k",
"Gender": "1",
"BirthDate": "2010-03-05T00:00:00",
"Birthplace": "spain",
"Nationality": "0001",
"DateOfDeath": "2023-03-09T00:00:00+01:00",
"UserUID": "046588",
"CommunicationLanguage": "NL",
"PhoneNumbers": [
{
"Type": "Mobile",
"Number": "085282265"
},
{
"Type": "Private",
"Number": "532186503"
}
],
"EmailAddresses": [
{
"Type": "Private",
"Email": "test@visma.com"
},
{
"Type": "Work",
"Email": "test2@visma.com"
}
]
},
"Addresses": [
{
"Type": "Home",
"Country": "NL",
"Street": "wigsfrfvpb",
"HouseNumber": "17",
"HouseNumberAddition": "25",
"PostalCode": "1234 AB",
"Municipality": "kkvviybree",
"Location": "guufgvstcy",
"Region": "xhcvjoprbh"
},
{
"Type": "Postal",
"Country": "NL",
"Street": "golurxcftu",
"HouseNumber": "13",
"HouseNumberAddition": "06",
"PostalCode": "1234 AB",
"Municipality": "ponccrykpq",
"Location": "xhfjpfbkmu",
"Region": "cndsqcxmkt"
}
],
"BankAccounts": [
{
"Id": 1,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "tksapvnxfq",
"AccountType": "01",
"AccountHolder": "stppb",
"Amount": "100,5"
},
{
"Id": 2,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "wxrhuivevj",
"AccountType": "01",
"AccountHolder": "nqvmq",
"Amount": "100,5"
},
{
"Id": 3,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "jipeavrepm",
"AccountType": "01",
"AccountHolder": "nnfkk",
"Amount": "100,5"
},
{
"Id": 4,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "wnwifysqin",
"AccountType": "01",
"AccountHolder": "gcimf",
"Amount": "100,5"
},
{
"Id": 5,
"Iban": "GB33BUKB20201555555555",
"Bic": "MOLUNL22",
"Description": "rkqdbeusep",
"AccountType": "01",
"AccountHolder": "ckocx",
"Amount": "100,5"
}
]
}
As it is an asynchronous operation, you will get a requestId to check using the Get request status endpoint.
{
"requestId": "c0abf203-f569-445a-823b-921d702785e6"
}
Contracts
These endpoints return the data of the contracts. Each field has its own timeline.
Get all contracts of a customer:
- Get: https://api.youserve.nl/hrp/v1.0/contracts
Get all contracts of an employee:
- Get: https://api.youserve.nl/hrp/v1.0/contracts?employeeId=10030024
Get the data of a contract:
- Get: https://api.youserve.nl/hrp/v1.0/contracts/10030025
Response example:
{
"employeeId": 10036130,
"companyCode": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "9999-12-31T00:00:00+00:00",
"value": "1"
}
],
"personCode": [],
"employeeCode": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "9999-12-31T00:00:00+00:00",
"value": "594"
}
],
"initials": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "9999-12-31T00:00:00+00:00",
"value": "GH"
}
],
"lastName": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "9999-12-31T00:00:00+00:00",
"value": "Meer"
}
],
"contractId": 10030025,
"employmentCode": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "1"
}
],
"description": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "TestPatch"
}
],
"jobProfile": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Proj_L"
}
],
"daysPeriod": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "2023-03-22T00:00:00Z",
"value": "5"
},
{
"startDate": "2022-12-01T00:00:00Z",
"endDate": "2022-12-31T00:00:00",
"value": "5"
},
{
"startDate": "2023-01-01T00:00:00Z",
"endDate": "2023-01-31T00:00:00",
"value": "4"
},
{
"startDate": "2023-02-01T00:00:00Z",
"endDate": "2023-03-22T00:00:00",
"value": "5"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "2023-03-24T00:00:00Z",
"value": "7"
},
{
"startDate": "2023-03-25T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "7"
}
],
"hoursPeriod": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "2015-02-28T00:00:00Z",
"value": "40"
},
{
"startDate": "2015-03-01T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "36"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "2023-03-24T00:00:00Z",
"value": "3"
},
{
"startDate": "2023-03-25T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "3"
}
],
"contractType": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "B"
}
],
"location": [],
"costCenter": [],
"collectiveLaborAgreement": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "10027028"
}
],
"contractEndDate": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "9999-12-31"
}
],
"department": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "BD"
}
],
"incomeRelationshipNumber": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "16"
}
],
"writtenLaborAgreement": [
{
"startDate": "2019-10-31T00:00:00Z",
"endDate": "9999-12-31T00:00:00",
"value": "J"
},
{
"startDate": "2019-11-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00",
"value": "J"
}
],
"onCallAgreement": [
{
"startDate": "2019-10-31T00:00:00Z",
"endDate": "9999-12-31T00:00:00",
"value": "N"
},
{
"startDate": "2019-11-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00",
"value": "N"
}
],
"mainOrAncillaryContract": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "9999-12-31T00:00:00+00:00",
"value": "1"
}
],
"probationaryPeriod": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "9999-12-31T00:00:00+00:00",
"value": "0"
}
],
"hireDate": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "9999-12-31T00:00:00+00:00",
"value": "1996-11-01"
}
],
"firstHireDate": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "9999-12-31T00:00:00+00:00",
"value": "1996-11-01"
}
],
"establishmentUnit": [
{
"startDate": "2006-01-01T00:00:00+00:00",
"endDate": "9999-12-31T00:00:00+00:00",
"value": "10054050"
}
],
"organizationalUnit": [
{
"startDate": "2023-04-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00",
"value": "13234918"
}
]
}
This endpoint allows to update an employee. The request body is fixed and the missing fields are ignored. The start date is mandatory.
- Patch: https://api.youserve.nl/hrp/v1.0/contracts/10031392
Request body example:
{
"startDate": "2023-04-24",
"employmentCode": "2",
"description": "stringTest",
"jobProfile": "AF",
"daysPeriod": 7,
"hoursPeriod": 9,
"contractType": "C",
"location": "Madrid",
"costCenter": "01",
"collectiveLaborAgreement": 10027028,
"contractEndDate": "2026-01-01",
"department": "AF",
"incomeRelationshipNumber": 2,
"writtenLaborAgreement": "K",
"onCallAgreement": "Y",
"mainOrAncillaryContract": "0",
"probationaryPeriod": "5",
"hireDate": "2023-04-24",
"firstHireDate": "2000-01-01",
"establishmentUnit": "10054051",
"organizationalUnit": "10641457"
}
As it is an asynchronous operation, you will get a requestId to check using the Get request status endpoint.
{
"requestId": "2788965b-bafb-4cc8-a235-3dd0efb3ffae"
}
Benefits
These endpoints return the data of the benefits: Salary scale or Gross variable. The timeline is associated to the set of fields.
Get the Salary scale data of a contract:
- Get: https://api.youserve.nl/hrp/v1.0/contracts/10030338/salaryScale
Response example:
[
{
"validFrom": "2006-01-01T00:00:00",
"validUntil": "2008-06-30T00:00:00",
"contractId": 10030338,
"employeeId": 10033542,
"personCode": null,
"employeeCode": "592",
"initials": "M.",
"lastName": "Ruiter",
"companyCode": "2",
"employmentCode": "1",
"salaryPeriodicity": "13",
"salaryScale": null,
"salaryLevel": 0,
"rsp": 0,
"category": null,
"factorToConvertAnnualSalary": 0,
"autoIncreaseLevelBasedOnAge": false,
"autoLevelIncreaseBasedOnYearsInService": false,
"blockCollectiveSalaryIncrease": false,
"assessmentScore": null,
"blockIncreaseOfSalaryBasedOnAssessment": false,
"salaryAmount": 0
},
{
"validFrom": "2008-07-01T00:00:00",
"validUntil": "2012-02-29T00:00:00",
"contractId": 10030338,
"employeeId": 10033542,
"personCode": null,
"employeeCode": "592",
"initials": "M.",
"lastName": "Ruiter",
"companyCode": "2",
"employmentCode": "1",
"salaryPeriodicity": "13",
"salaryScale": "10",
"salaryLevel": 0,
"rsp": 0,
"category": null,
"factorToConvertAnnualSalary": 0,
"autoIncreaseLevelBasedOnAge": false,
"autoLevelIncreaseBasedOnYearsInService": false,
"blockCollectiveSalaryIncrease": false,
"assessmentScore": null,
"blockIncreaseOfSalaryBasedOnAssessment": false,
"salaryAmount": 500
},
{
"validFrom": "2012-03-01T00:00:00",
"validUntil": "2012-12-30T00:00:00",
"contractId": 10030338,
"employeeId": 10033542,
"personCode": null,
"employeeCode": "592",
"initials": "M.",
"lastName": "Ruiter",
"companyCode": "2",
"employmentCode": "1",
"salaryPeriodicity": "13",
"salaryScale": "10",
"salaryLevel": 0,
"rsp": 0,
"category": null,
"factorToConvertAnnualSalary": 0,
"autoIncreaseLevelBasedOnAge": false,
"autoLevelIncreaseBasedOnYearsInService": false,
"blockCollectiveSalaryIncrease": false,
"assessmentScore": null,
"blockIncreaseOfSalaryBasedOnAssessment": false,
"salaryAmount": 500
},
{
"validFrom": "2012-12-31T00:00:00",
"validUntil": "2013-12-31T00:00:00",
"contractId": 10030338,
"employeeId": 10033542,
"personCode": null,
"employeeCode": "592",
"initials": "M.",
"lastName": "Ruiter",
"companyCode": "2",
"employmentCode": "1",
"salaryPeriodicity": "13",
"salaryScale": "10",
"salaryLevel": 0,
"rsp": 0,
"category": null,
"factorToConvertAnnualSalary": 0,
"autoIncreaseLevelBasedOnAge": false,
"autoLevelIncreaseBasedOnYearsInService": false,
"blockCollectiveSalaryIncrease": false,
"assessmentScore": null,
"blockIncreaseOfSalaryBasedOnAssessment": false,
"salaryAmount": 500
},
{
"validFrom": "2014-01-01T00:00:00",
"validUntil": "9999-12-31T00:00:00",
"contractId": 10030338,
"employeeId": 10033542,
"personCode": null,
"employeeCode": "592",
"initials": "M.",
"lastName": "Ruiter",
"companyCode": "2",
"employmentCode": "1",
"salaryPeriodicity": "13",
"salaryScale": "10",
"salaryLevel": 0,
"rsp": 0,
"category": null,
"factorToConvertAnnualSalary": 0,
"autoIncreaseLevelBasedOnAge": false,
"autoLevelIncreaseBasedOnYearsInService": false,
"blockCollectiveSalaryIncrease": false,
"assessmentScore": null,
"blockIncreaseOfSalaryBasedOnAssessment": false,
"salaryAmount": 2075
}
]
Get the Gross variable data of a contract:
- Get: https://api.youserve.nl/hrp/v1.0/contracts/10030778/grossVariable
Response example:
[
{
"validFrom": "2006-01-01T00:00:00",
"validUntil": "2012-12-30T00:00:00",
"employeeId": 10033760,
"personCode": null,
"employeeCode": "602",
"initials": "K.",
"lastName": "Buiten",
"contractId": 10030778,
"companyCode": "2",
"employmentCode": "1",
"salaryHourlyRate": 0,
"salaryHoursWorked": 0,
"salaryDaysWorked": 0,
"salaryScale": null,
"salaryLevel": 0,
"rsp": 0,
"alternateSalaryHourlyWages": 0,
"autoIncreaseLevelBasedOnAge": false,
"autoLevelIncreaseBasedOnYearsInService": false
},
{
"validFrom": "2012-12-31T00:00:00",
"validUntil": "2013-08-31T00:00:00",
"employeeId": 10033760,
"personCode": null,
"employeeCode": "602",
"initials": "K.",
"lastName": "Buiten",
"contractId": 10030778,
"companyCode": "2",
"employmentCode": "1",
"salaryHourlyRate": 0,
"salaryHoursWorked": 0,
"salaryDaysWorked": 0,
"salaryScale": null,
"salaryLevel": 0,
"rsp": 0,
"alternateSalaryHourlyWages": 0,
"autoIncreaseLevelBasedOnAge": false,
"autoLevelIncreaseBasedOnYearsInService": false
},
{
"validFrom": "2013-09-01T00:00:00",
"validUntil": "2015-11-30T00:00:00",
"employeeId": 10033760,
"personCode": null,
"employeeCode": "602",
"initials": "K.",
"lastName": "Buiten",
"contractId": 10030778,
"companyCode": "2",
"employmentCode": "1",
"salaryHourlyRate": 0,
"salaryHoursWorked": 0,
"salaryDaysWorked": 0,
"salaryScale": null,
"salaryLevel": 0,
"rsp": 0,
"alternateSalaryHourlyWages": 0,
"autoIncreaseLevelBasedOnAge": false,
"autoLevelIncreaseBasedOnYearsInService": false
},
{
"validFrom": "2015-12-01T00:00:00",
"validUntil": "2015-12-31T00:00:00",
"employeeId": 10033760,
"personCode": null,
"employeeCode": "602",
"initials": "K.",
"lastName": "Buiten",
"contractId": 10030778,
"companyCode": "2",
"employmentCode": "1",
"salaryHourlyRate": 10,
"salaryHoursWorked": 160,
"salaryDaysWorked": 20,
"salaryScale": null,
"salaryLevel": 0,
"rsp": 0,
"alternateSalaryHourlyWages": 0,
"autoIncreaseLevelBasedOnAge": false,
"autoLevelIncreaseBasedOnYearsInService": false
},
{
"validFrom": "2016-01-01T00:00:00",
"validUntil": "2016-01-31T00:00:00",
"employeeId": 10033760,
"personCode": null,
"employeeCode": "602",
"initials": "K.",
"lastName": "Buiten",
"contractId": 10030778,
"companyCode": "2",
"employmentCode": "1",
"salaryHourlyRate": 10,
"salaryHoursWorked": 152,
"salaryDaysWorked": 19,
"salaryScale": null,
"salaryLevel": 0,
"rsp": 0,
"alternateSalaryHourlyWages": 0,
"autoIncreaseLevelBasedOnAge": false,
"autoLevelIncreaseBasedOnYearsInService": false
},
{
"validFrom": "2016-02-01T00:00:00",
"validUntil": "2016-02-29T00:00:00",
"employeeId": 10033760,
"personCode": null,
"employeeCode": "602",
"initials": "K.",
"lastName": "Buiten",
"contractId": 10030778,
"companyCode": "2",
"employmentCode": "1",
"salaryHourlyRate": 10,
"salaryHoursWorked": 100,
"salaryDaysWorked": 13,
"salaryScale": null,
"salaryLevel": 0,
"rsp": 0,
"alternateSalaryHourlyWages": 0,
"autoIncreaseLevelBasedOnAge": false,
"autoLevelIncreaseBasedOnYearsInService": false
},
{
"validFrom": "2016-03-01T00:00:00",
"validUntil": "9999-12-31T00:00:00",
"employeeId": 10033760,
"personCode": null,
"employeeCode": "602",
"initials": "K.",
"lastName": "Buiten",
"contractId": 10030778,
"companyCode": "2",
"employmentCode": "1",
"salaryHourlyRate": 10,
"salaryHoursWorked": 0,
"salaryDaysWorked": 0,
"salaryScale": null,
"salaryLevel": 0,
"rsp": 0,
"alternateSalaryHourlyWages": 0,
"autoIncreaseLevelBasedOnAge": false,
"autoLevelIncreaseBasedOnYearsInService": false
}
]
This endpoint allows to update the salary scale data of a contract. The request body is fixed and the missing fields are ignored. The start date is mandatory.
- Patch: https://api.youserve.nl/hrp/v1.0/contracts/10030025/salaryScale
Request body example:
{
"startDate": "2023-03-23",
"salaryPeriodicity": "13",
"salaryScale": "2",
"salaryLevel": 11,
"rsp": 8,
"category": "2",
"factorToConvertAnnualSalary": 1,
"autoIncreaseLevelBasedOnAge": true,
"autoLevelIncreaseBasedOnYearsInService": false,
"blockCollectiveSalaryIncrease": true,
"blockIncreaseOfSalaryBasedOnAssessment": true,
"salaryAmount": 1000
}
This endpoint allows to update the gross variable data of a contract. The request body is fixed and the missing fields are ignored. The start date is mandatory.
- Patch: https://api.youserve.nl/hrp/v1.0/contracts/10030025/grossVariable
Request body example:
{
"startDate": "2023-03-23",
"salaryHourlyRate": 8,
"salaryHoursWorked": 8,
"salaryDaysWorked": 5,
"salaryScale": "2",
"salaryLevel": 11,
"rsp": 8,
"alternateSalaryHourlyWages": 2,
"autoIncreaseLevelBasedOnAge": true,
"autoLevelIncreaseBasedOnYearsInService": false
}
As they are asynchronous operations, you will get a requestId to check using the Get request status endpoint.
{
"requestId": "366c639d-0336-4818-8394-4116f8cf8bbe"
}
Value lists
These endpoints return the different value lists used in the employee and contract data. It is possible to set filters for language and reference date.
Marital statuses:
- Get: https://api.youserve.nl/hrp/v1.0/maritalStatuses
- Get: https://api.youserve.nl/hrp/v1.0/maritalStatuses?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/maritalStatuses?referenceDate=2023-01-01
Genders:
- Get: https://api.youserve.nl/hrp/v1.0/genders
- Get: https://api.youserve.nl/hrp/v1.0/genders?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/genders?referenceDate=2023-01-01
Nationalities:
- Get: https://api.youserve.nl/hrp/v1.0/nationalities
- Get: https://api.youserve.nl/hrp/v1.0/nationalities?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/nationalities?referenceDate=2023-01-01
Communication Languages:
- Get: https://api.youserve.nl/hrp/v1.0/communicationLanguages
- Get: https://api.youserve.nl/hrp/v1.0/communicationLanguages?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/communicationLanguages?referenceDate=2023-01-01
Countries: (Address types: Home or Postal)
- Get: https://api.youserve.nl/hrp/v1.0/countries?addressType=Home
- Get: https://api.youserve.nl/hrp/v1.0/countries?addressType=Home&language=NL
- Get: https://api.youserve.nl/hrp/v1.0/countries?addressType=Home&referenceDate=2023-01-01
Account Types: (AccountTypeId: 1 - 10)
- Get: https://api.youserve.nl/hrp/v1.0/accountTypes?accountTypeId=1
- Get: https://api.youserve.nl/hrp/v1.0/accountTypes?accountTypeId=1&language=NL
- Get: https://api.youserve.nl/hrp/v1.0/accountTypes?accountTypeId=1&referenceDate=2023-01-01
Job Profiles:
- Get: https://api.youserve.nl/hrp/v1.0/jobProfiles
- Get: https://api.youserve.nl/hrp/v1.0/jobProfiles?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/jobProfiles?referenceDate=2023-01-01
Contract Types:
- Get: https://api.youserve.nl/hrp/v1.0/contractTypes
- Get: https://api.youserve.nl/hrp/v1.0/contractTypes?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/contractTypes?referenceDate=2023-01-01
Locations:
- Get: https://api.youserve.nl/hrp/v1.0/locations
- Get: https://api.youserve.nl/hrp/v1.0/locations?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/locations?referenceDate=2023-01-01
Classifications:
- Get: https://api.youserve.nl/hrp/v1.0/classifications
- Get: https://api.youserve.nl/hrp/v1.0/classifications?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/classifications?referenceDate=2023-01-01
Cost Centers:
- Get: https://api.youserve.nl/hrp/v1.0/costCenters
- Get: https://api.youserve.nl/hrp/v1.0/costCenters?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/costCenters?referenceDate=2023-01-01
Salary Scales:
- Get: https://api.youserve.nl/hrp/v1.0/salaryScales
- Get: https://api.youserve.nl/hrp/v1.0/salaryScales?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/salaryScales?referenceDate=2023-01-01
Departments:
- Get: https://api.youserve.nl/hrp/v1.0/departments
- Get: https://api.youserve.nl/hrp/v1.0/departments?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/departments?referenceDate=2023-01-01
Written Labor Agreements:
- Get: https://api.youserve.nl/hrp/v1.0/writtenLaborAgreements
- Get: https://api.youserve.nl/hrp/v1.0/writtenLaborAgreements?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/writtenLaborAgreements?referenceDate=2023-01-01
On Call Agreements:
- Get: https://api.youserve.nl/hrp/v1.0/onCallAgreements
- Get: https://api.youserve.nl/hrp/v1.0/onCallAgreements?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/onCallAgreements?referenceDate=2023-01-01
Main or Ancillary Contracts:
- Get: https://api.youserve.nl/hrp/v1.0/mainOrAncillaryContracts
- Get: https://api.youserve.nl/hrp/v1.0/mainOrAncillaryContracts?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/mainOrAncillaryContracts?referenceDate=2023-01-01
Probationary Periods:
- Get: https://api.youserve.nl/hrp/v1.0/probationaryPeriods
- Get: https://api.youserve.nl/hrp/v1.0/probationaryPeriods?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/probationaryPeriods?referenceDate=2023-01-01
Employment Types:
- Get: https://api.youserve.nl/hrp/v1.0/employmentTypes
- Get: https://api.youserve.nl/hrp/v1.0/employmentTypes?language=NL
- Get: https://api.youserve.nl/hrp/v1.0/employmentTypes?referenceDate=2023-01-01
Response example of the previous value lists:
[
{
"code": "0",
"description": "Unknown"
},
{
"code": "1",
"description": "Single"
},
{
"code": "2",
"description": "Wed"
},
{
"code": "3",
"description": "Divorced"
},
{
"code": "4",
"description": "Widow/widower"
},
{
"code": "5",
"description": "Registered partnership"
},
{
"code": "6",
"description": "Cohabiting"
},
{
"code": "7",
"description": "Cohabiting without contract"
},
{
"code": "8",
"description": "Cohabiting with contract"
}
]
Collective Labour Agreements:
- Get: https://api.youserve.nl/hrp/v1.0/collectiveLabourAgreements
- Get: https://api.youserve.nl/hrp/v1.0/collectiveLabourAgreements/10025352
Response example:
{
"id": 10025352,
"code": [
{
"startDate": "2001-01-01T00:00:00+00:00",
"endDate": "2023-03-22T00:00:00Z",
"value": "487"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "codeUpd"
}
],
"workSchedule": [
{
"startDate": "2001-12-30T00:00:00Z",
"endDate": "2023-03-22T00:00:00",
"value": "1111122000000000000000000000"
},
{
"startDate": "2001-12-31T00:00:00Z",
"endDate": "2023-03-22T00:00:00",
"value": "1111122000000000000000000000"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "workScheduleUpd"
}
],
"client": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "10029306"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "10029306"
}
],
"nameImplementationCompany": [
{
"startDate": "2001-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "NameImplementationArt"
}
],
"name": [
{
"startDate": "2001-01-01T00:00:00+00:00",
"endDate": "2023-03-22T00:00:00Z",
"value": "Raet Demo Administratie NL"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "testName"
}
],
"workHoursScheduleWeek1": [
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "112"
}
],
"flexBundleIdentification": [],
"employerCategory": [],
"sequenceNumber": [
{
"startDate": "2001-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "00002"
}
]
}
This endpoint allows to create a new company collective labour agreement:
Post: https://api.youserve.nl/hrp/v1.0/collectiveLabourAgreements
Request body example:
{
"companyId": 13155436,
"startDate": "2023-09-05",
"code": "CodeArt2",
"workSchedule": "WorkScheduleArt",
"client": "10029306",
"nameImplementationCompany": "NameImplementationArt",
"name": "Name4",
"workHoursScheduleWeek1": "112",
"sequenceNumber": "0007"
}
As it is an asynchronous operation, you will get a requestId to check using the Get request status endpoint.
{
"requestId": "c2c131ce-59ef-4ab5-b60f-c0a68474fc28"
}
This endpoint allows to update a company collective labour agreement. The body is fixed and the missing fields are ignored.
Patch: https://api.youserve.nl/hrp/v1.0/collectiveLabourAgreements/14073663
Request body example:
{
"startDate": "2023-02-02",
"code": "CodeArt2",
"workSchedule": "WorkScheduleArt",
"client": "10029306",
"nameImplementationCompany": "NameImplementationArt",
"name": "Name4",
"workHoursScheduleWeek1": "112",
"sequenceNumber": "0008"
}
As it is an asynchronous operation, you will get a requestId to check using the Get request status endpoint.
{
"requestId": "c2c131ce-59ef-4ab5-b60f-c0a68474fc28"
}
Organizational Units:
- Get: https://api.youserve.nl/hrp/v1.0/organizationalUnits
- Get: https://api.youserve.nl/hrp/v1.0/organizationalUnits/10641457
Response example:
{
"id": 10641457,
"code": [
{
"startDate": "2009-11-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "ILaYVs"
}
],
"name": [
{
"startDate": "2009-11-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "name"
}
],
"backupManager": [
{
"startDate": "2009-11-01T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "10647865"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "13375375"
}
],
"numberOfFTEs": [
{
"startDate": "2009-11-01T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "12"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "1"
}
],
"manager": [
{
"startDate": "2009-11-01T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "10033037"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "10033037"
}
],
"numberKvK": [],
"organizationType": [
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "01"
}
],
"numberOfEmployees": [
{
"startDate": "2009-11-01T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "12"
}
],
"yearEstimation": [
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "1212"
}
],
"educationBudget": [
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "2121"
}
]
}
This endpoint allows to create a new organizational unit:
Post: https://api.youserve.nl/hrp/v1.0/organizationalUnits
Request body example:
{
"tenantId": 10029872,
"startDate": "2023-01-01",
"code": "ART1",
"name": "name",
"backupManager": "13375375",
"numberOfFTEs": "1",
"manager": "10033037",
"numberKvK": "11",
"organizationType": "01",
"numberOfEmployees": "12",
"yearEstimation": "2023",
"educationBudget": "455"
}
As it is an asynchronous operation, you will get a requestId to check using the Get request status endpoint.
{
"requestId": "99045997-77e5-46b0-8657-8a3612e3f9d8"
}
This endpoint allows to update an organizational unit. The body is fixed and the missing fields are ignored.
Patch: https://api.youserve.nl/hrp/v1.0/organizationalUnits/14075602
Request body example:
{
"startDate": "2023-01-01",
"code": "ART51",
"name": "nameUp",
"backupManager": "13375375",
"numberOfFTEs": "11",
"manager": "10033037",
"numberKvK": "111",
"organizationType": "01",
"numberOfEmployees": "121",
"yearEstimation": "20231",
"educationBudget": "4551"
}
As it is an asynchronous operation, you will get a requestId to check using the Get request status endpoint.
{
"requestId": "2cec716f-34f7-4602-b81c-a1c074d2937e"
}
Establishment Units:
- Get: https://api.youserve.nl/hrp/v1.0/establishmentUnits
- Get: https://api.youserve.nl/hrp/v1.0/establishmentUnits/10054043
Response example:
{
"id": 10054043,
"code": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "@710e1"
}
],
"name": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Ve8l7t"
}
],
"numberKvK": [],
"addresses": [
{
"type": "WorkLocation",
"country": [],
"regionNameAbroad": [],
"municipality": [],
"location": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "2017-12-31T00:00:00Z",
"value": "Amersfoort"
},
{
"startDate": "2018-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Enschede"
}
],
"locationDescription": [],
"street": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "2017-12-31T00:00:00Z",
"value": "Vlasblom"
},
{
"startDate": "2018-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "Rembrandtlaan"
}
],
"streetHouseNumber": [],
"houseNumber": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "2017-12-31T00:00:00Z",
"value": "34"
},
{
"startDate": "2018-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "225"
}
],
"houseNumberSuffix": [],
"postalCode": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "2017-12-31T00:00:00Z",
"value": "9999 AA"
},
{
"startDate": "2018-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "7545 ZW"
}
]
},
{
"type": "Mailing",
"country": [
{
"startDate": "2016-04-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "NL"
}
],
"regionNameAbroad": [],
"municipality": [],
"location": [],
"locationDescription": [],
"street": [],
"streetHouseNumber": [],
"houseNumber": [],
"houseNumberSuffix": [],
"postalCode": []
}
],
"website": [
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "www.added.com"
}
],
"emailAddress": [],
"telephoneNumber": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "2023-03-22T00:00:00Z",
"value": "033-4506506"
},
{
"startDate": "2023-03-23T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "112"
}
],
"faxNumber": [
{
"startDate": "2006-01-01T00:00:00Z",
"endDate": "9999-12-31T00:00:00Z",
"value": "033-4506708"
}
]
}
Request status
All asynchronous operations return a requestId. This endpoint allows to check the status of the request using the requestId.
Get the addresses of all employees of a customer:
- Get: https://api.youserve.nl/hrp/v1.0/requests/31118e5d-cc72-4d43-a644-57a1afbed118
Response example: (in failure)
{
"processStatus": "Finished",
"timeStamp": "2023-03-27 08:48:39",
"result": {
"status": "Failed",
"errorMessages": [
"Value in field is not unique within: Company"
]
}
}
Workflows
This endpoint allows to start a workflow in HRSS, previously defined and configured to be started by the HRPAPI:
Post: https://api.youserve.nl/hrp/v1.0/workflows/{workflowName}/start
Request body example:
{
"fields": [
{
"name": "testmyStreet",
"value": "required"
}
],
"employeeFields": {
"employeeId": "10036130",
"contractNumber": "1"
},
"files": [{
"name": "test.txt",
"category": "",
"contentBase64": "YQ=="
}
]
}
Response example:
{
"data": {
"workflowInstanceId": 327650
},
"error": null
}
This endpoint allows to check the status of the workflow instance created in HRSS by the previous endpoint:
Get: https://api.youserve.nl/hrp/v1.0/workflows/{workflowInstanceId}
Response example:
{
"data": {
"isActive": true,
"currentActivity": "Tekenen",
"endStatus": "InProgress",
"endStatusName": "",
"workflowInstanceId": 327650
},
"error": null
}
These endpoints allow to get the details of the workflow definitions for the tenant:
Get: https://api.youserve.nl/hrp/v1.0/workflowsDefinitions
Get: https://api.youserve.nl/hrp/v1.0/workflowsDefinitions/{WF_Name}
Response example:
[
{
"name": "PVT Address",
"activity": "Indienen",
"button": "Verzenden",
"fields": [
{
"name": "testmyStreet",
"hrssElement": "391PS",
"isRequired": true
}
],
"defaultFields": [],
"employeeIdRequired": true,
"contractNumberRequired": false,
"departmentIdRequired": false,
"enableFormFieldScript": true,
"enableFormValidation": false,
"enableDialogConditionScript": true,
"attachmentsRequired": false
}
]
Postman collection and environment
As attachment you can find a zip file with the collection and the environment.
... View more
Labels:
09-10-2023
10:36
1 Kudo
This API is intended for external HR solutions and other external consumers in order to create and update data in HR Core and Payroll.
This is an entity driven API, based on the following entities:
Employee: Person that belongs to a company
Contract: Employee in a specific position
Payroll data: Benefits, fixed payments and one off payment of an employee
Value lists
Fixed payments
One off payments
Workflows
Employee
De beschikbare velden voor dit end-point zijn terug te vinden in de bijlage "HR Core and Payroll API - Domain model and concepts.xlsx"
Contract
De beschikbare velden voor dit end-point zijn terug te vinden in de bijlage "HR Core and Payroll API - Domain model and concepts.xlsx"
Salary Scale
De beschikbare velden voor dit end-point zijn terug te vinden in de bijlage "HR Core and Payroll API - Domain model and concepts.xlsx"
Value lists and other entities
Company Collective Labor Agreement
Element Number
Label
Description
47
Code
Code
65
WorkSchedule
Work Schedule
191
ClientCLA
Client CLA
194
NameCLAImplementationCompany
Name CLA Implementation Company
549
Name
Name
565
WorkHoursScheduleWeek1
Work Hours Schedule Week 1
587
FlexBundleIdentification
Flex Bundle Identification
893
EmployerCategory
Employer Category
10520175
SequenceNumberCompanyCLA
Sequence Number Company CLA
18
CompanyCode
Company Code
Organizational Unit
Element Number
Label
Description
548
Code
Code
549
Name
Name
7011
BackupManager
Backup Manager
7012
NumberOfFTEs
Number Of FTEs
7137
Manager
Manager
7271
NumberKvK
Number KvK
7475
OrganizationType
Organization Type
7476
NumberOfEmployees
Number Of Employees
7477
YearEstimation
Year Estimation
7478
EducationBudget
Education Budget
Establishment Unit
Element Number
Label
Description
147
StreetHouseNumber
Street House Number
548
Code
Code
7271
NumberKvK
Number KvK
7375
FaxNumber
Fax Number
7380
HouseNumberMailingAddress
House Number Mailing Address
7381
MunicipalityMailingAddress
Municipality Mailing Address
7382
PostalCodeMailingAddress
Postal Code Mailing Address
7383
StreetMailingAddress
Street Mailing Address
7384
HouseNumberSuffixMailingAddress
House Number Suffix Mailing Address
7415
TelephoneNumber
Telephone Number
7445
WorklocationName
Worklocation Name
7446
Location
Location
7447
EmailAddress
Email Address
7451
HouseNumber
House Number
7452
HouseNumberSuffix
House Number Suffix
7453
PostCode
PostCode
7454
Street
Street
7456
Website
Website
7571
CountryMailingAddress
Country Mailing Address
8099
LocationDescription
Location Description
8100
LocationDescriptionMailingAddress
Location Description Mailing Address
8101
RegionNameAbroadMailingAddress
Region Name Abroad Mailing Address
8110
Country
Country
10205283
NameRegionAbroad
Name Region Abroad
Values lists
Employee
MaritalStatus - 37
Gender - 36
Nationality - 10204761
Communication Language - 10
34 Home Address - 7571 Postal Address - Country
AccountType1-10 (10000085,10000086,10000087,10000088,10000089,10000090,10000091,10000092,10000093,10000094)
Contract
JobProfile - 97
ContractType - 10204687
Location - 75
Classification - 474
CostCenter - 53
Salary Scale - 10300574
Department - 96
writtenLaborAgreement - 10524364
onCallAgreement - 10524365
mainOrAncillaryContract - 10524210
probationaryPeriod - 7145
EmploymentType - 7393
The value list endpoints return a list of codes and descriptions.
Start workflows
To start a workflow in HRSS by this API, there should be a definition of the allowed workflows for the tenant. This configuration is done by the consultants. You can check the details of the defined workflows using the get endpoint for workflow definitions.
... View more
19-05-2023
17:13
19-05-2023: Added 7 Belgian custom fields
Employees endpoint - The following custom fields were added as part of the extensions of the contract:
BirthcountryBE - Geboorteland [BE] - 10528257
Nationality - Nationaliteit - 10519287
CountryBE - Woonland [BE] - 10528256
FunctionLevelBE - Functieniveau [BE] - 10528456
DepartureReasonBE - Reden ontslag [BE] - 10528258
HospitalisationInsurancep18 - Hospitalisatieverzekering +18 [BE] - 10528431
HospitalisationInsurancem18 - Hospitalisatieverzekering -18 [BE] - 10528432
Endpoint documentation is updated.
... View more
28-01-2022
11:26
This API is intended for recruiting systems and allows them to get the data needed for the recruiting process and send the candidate to be hired.
Candidates
Technical flow
The candidate endpoint is asynchronous:
The recruiting sends in the new hire or contract change.
Youforce will
Validate the incoming data
Trigger Id Scan (optional)
Start a process based on configuration of the customer
The recruiting system checks if the hire has been accepted.
Steps 3 is critical. The process is only accepted by Youforce when the status is 'Completed'. It is the responsibility of the recruiting system to check if the hire is successfully trigged by based on the entered data. There are no user feedback mechanisms in Youforce that inform a hiring manager that the new hire has not been accepted by Youforce.
Candidate data
Property
Description
Mandatory
Example
Data type
candidateID
The ID of the candidate in the recruiting system. This field is available as free field in the Core for Reporting purpose.
Yes
0001
string
PersonData
Fields related to the person
PersonalDetails: last name, first names, date of birth, etc
PhoneNumbers: list of phone numbers
One is mandatory
emailAdress: Private email address to contact the candidate.
Yes
candidate@private.com
string
Addresses: list of addresses
PersonalDetails
Fields related to personal data
lastNameAtBirth: The last name at birth of the candidate. Also the family name.
string
lastNameAtBirthPrefix: The prefix of the last name at birth.
string
knownAs: The name which is used by the candidate as his first name.
string
initials: The initials of the candidate.
string
firstNames: The official given names of the candidate.
string
lastName: The last name the candidate is currently using.
Yes
string
gender: The gender of the candidate.
(0) Not known
(1) Male
(2) Female
(9) Not applicable
To use 0 and 9 values, they must be configured in the core system.
string
birthDate: Date of birth of the candidate.
DateTime
birthPlace: The place of birth of the candidate.
string
birthCountry: The country of birth of the candidate.
string
primaryNationality: The nationality of the candidate.
string
titlePrefix: The formal title which will be used as a prefix before the name.
string
titleSuffix: The formal title which will be used as suffix after the name.
string
maritalStatus: The marital status of the candidate.
string
lastNamePreference: A code that indicates the preferred last name of the employee. for instance
last name at birth
last name partner
last name partner + last name at birth
last name at birth + last name partner
string
lastNamePartner: The partner last name.
string
partnerNamePrefix: The prefix of the partner last name.
string
socialSecurityNumber: Social Security Number of the candidate.
string
phoneNumber
details of the phone number
type: home, mobile
home
string
number
+ 31 0624829858
string
Address
Fields related to the address of the candidate
type: home, postal
home
string
streetName: Street name
Wamberg
string
number: House number
69
string
NumberAdditional: additional number
34
string
locationDescription: location
string
postalCode: Postal code
1083 CV
string
city: City
Amsterdam
string
region: Region
string
country: Country
The Netherlands
string
ApplicationDetails
Fields related with the application
vacancyNumberHR: Vacancy number in the HR Core systems. With this field the core system can check if the position is still open.
001
string
vacancyNumberATS: Vacancy number in the Applicant Tracking System. This field is available as free field for Reporting purpose.
1001
string
offerApproveDate: Date that the offer is approved in the ATS system. It is the date that the recruitment process ends and the onboarding of the new employee can start.
01-01-2021
DateTime
NewEmployement
Fields related to the new employement
payrollClient: The Id of payroll client in the core systems.
B2020
string
payrollCompany: The Id of payroll company in the core system.
Yes
C2020
string
collectiveLaborAgreement: Id of the collective labor agreement.
CAO01
string
hireDate: Proposed hire date of the Candidate.
Yes
01-01-2021
DateTime
endDate: If the contract is for a given time, this contains the end date of the employment.
31-12-2021
DateTime
contractType: Type of the contact.
Yes
01
string
probationPeriod: Indicates if a probation period is applied to the contract.
boolean
probationPeriodDuration: Duration of the probation period.
string
probationPeriodEnddate: End date of the probation period.
31-03-2021
DateTime
employeeType: Type of employment like Internal employee, contractor, etc.
Yes
001
string
organizationalUnit: Id of the organization unit of employment.
Yes
OU1
string
jobProfile: Job profile of the employment.
Yes
JP1
string
establishmentUnit: The logical code of location or establishment unit where the work is performed mainly in accordance with the contractual arrangement.
EU1
string
amountOfHours: Amount of working hours.
Yes
40
string
Salary: Fields related to the salary.
OtherBenefits: List of other benefits.
Salary
Fields related to the salary
salaryType: Type of salary
string
SalaryPeriodicity
string
SalaryAmount
string
ContractSalary
string
SalaryScale
string
SalaryGrade
string
RPSFactor
string
HourlyRateAmount
string
HourlyRateScale
string
hourlyRateGrade
string
Benefit
Fields to describe other benefits
benefitCode: Code of the benefit.
BEN01
string
value: Value of the benefit.
1000
string
CurrentEmployment
Fields related to current employement if exists.
PersonCode: Code of the person in the existing contract.
1000250
string
employmentCode: Code of the employment in the existing contract.
1
string
customFields
customField1
string
customField2
string
customField3
string
customField4
string
customField5
string
customField6
string
customField7
string
customField8
string
customField9
string
customField10
string
customField11
string
customField12
string
customField13
string
customField14
string
customField15
string
customField16
string
customField17
string
customField18
string
customField19
string
customField20
string
customField21
string
customField22
string
customField23
string
customField24
string
customField25
string
customField26
string
customField27
string
customField28
string
customField29
string
customField30
string
Vacancies DRAFT
⚠️ This is a draft endpoint. Vacancy data cannot be exposed at this moment. Please reach out to our community for more info.
Vacancy data
Property
Description
Example
Data type
VacancyCode
Unique vacancy number in the HR Core Self Service. This job request number is unique within the tenant.
VAC0012
string
Title
Title of the Vacancy
Case manager
string
organizationUnit
Logical code of the organization unit
HR01
string
payrollCompany
Logical code of the company
B01
string
recruitmentChannel
Channel in which the recruitment systems will publish the job request.
extern
string
jobProfile
Logical code of the Job profile
CMAN
string
jobLevel
Required level of the job like instance Junior, Medior or Senior
Medior
string
jobFamily
Logical code of the Job Family
HR
string
employeeType
Type of employee
Intern
string
amountHoursWeek
Amount of hours a week
40
string
contractType
Contract type
temporal
string
contractualDuration
Duration of the contract. Only relevant contract type is temporal.
1 year
string
establismentUnit
The logical code of the location or establishment unit where the work is performed, mainly in accordance with the contractual arrangement.
AMS
string
numberOfPositionsRequired
Total number of requested positions
5
string
numberOfPositionsCompleted
Total number of completed positions
3
string
ApprovalDate
Approval date of the job request
2020-12-20
string
startDate
Start date of the job request
2021-01-01
string
endDate
End date of the job request
2021-04-01
string
owner
Manager of the job request
J. Janssen
string
ownerEmailAddress
Email address of the owner of the job request
j.jansen@visma.com
string
RecruitmentReason
Indicates the reason for this new position. For instance because it is new position, extension of existing position or replacement of an existing person on a position.
Replacement
string
SalaryIndication
Indication for the salary, for instance a range like:
1500 - 1800 euro
or a maximum:
max 2000 euro
or a scale:
Scale 10
Schale 10
string
ExperienceLevel
ExperienceLevel
4-6
string
Extensions
List of additional fields configured in the HSS and the API
key
string
value
string
collectiveLaborAgreement
Collective Labor Agreement
string
salaryPeriodicity
Periodicity of the salary
string
salaryScale
Salary scale
string
salaryGrade
Salary Grade
string
customField1
string
customField2
string
customField3
string
customField4
string
customField5
string
customField6
string
customField7
string
customField8
string
customField9
string
customField10
string
customField11
string
customField12
string
customField13
string
customField14
string
customField15
string
customField16
string
customField17
string
customField18
string
customField19
string
customField20
string
customField21
string
customField22
string
customField23
string
customField24
string
customField25
string
customField26
string
customField27
string
customField28
string
customField29
string
customField30
string
ID scan
Customers can enable a Visma|Youserve ID Scan as part of their Recruiting API connections. This will increase data quality and ensure efficient administrative onboarding process. This is optional and needs to be enabled per customer.
The ID scan will complement or overwrite the data send by the recruiting system
The ID scan will be triggered once the candidate has been received from our system. The candidate will receive an invite to scan his identity document and complete his data.
The following data will be captured from the ID document:
Birth names (incl. prefix)
Initials
BSN
Nationality
Birthdate
Birthplace
Gender
Doc type
Document number
Document Registration Date
Document Expiry Date
The following data will be entered manually be the employee:
Firstname to use + prefix
Lastname to use + prefix
Bankaccount (IBAN - minimal validation)
Home address (street, number, postal, place, country)
Partner last name + prefix
Title for
Title after
ID Scans retention policy
Successfully processed IDs will be forwarded as attachments in the triggered Hire or Contract change process in Self Service. The Self-Service retention & archiving policies are applicable for these attachments.
The service responsible for scanning the IDs will retain IDs as follows:
Successfully processed ID will be removed after 24 hours. An ID is processed when the Recruiting API has retrieved the scan from the ID scan service.
Unprocessed ID will be removed after 2 weeks. So when the recruiting API was unable to fetch the ID scan for 2 weeks, the IDs will be automatically removed.
... View more
Labels:
28-01-2022
11:26
Swagger documentation
The following swagger page gives an overview of the endpoints:
Recruiting API
Endpoints
Candidates
Post candidate The endpoint Post candidate allows to send a candidate to be hired in the core system. This method returns the processId to check the status.
POST https://api.youserve.nl/recruiting/v1.0/candidates
There are 2 ways of calling this endpoint, with or without attachments. With attachments
The header Content-Type should be: multipart/related; boundary="A100x"; (The boundary is the one you choose). The total size of the request (all files and request body) is up to 100MB and the allowed file types are pdf, docx, txt, jpg, jpeg and png. Files cannot be empty.
The body should be splitted by sections, being the first one a json section with the candidate data as in the request without attachments.
For each attachment, there will be 2 sections:
json section: name of the file
--A100x Content-ID: <content> Content-Type: application/json
{ "Description":"contract.pdf" }
file section: content of the file
--A100x Content-ID: <content> Content-Type: application/pdf
%PDF-1.7 %·¾¬ª 1 0 obj << (this example is not complete)
Process status
After the candidate is posted to the API, the process can be followed with the status endpoint. The status of a process could be Pending, InProgress, WaitingOnValicare (if it is configured), Completed or Failed. Replace the ProcessId in the URL with the processId from the previous API call.
GET https://api.youserve.nl/recruiting/v1.0/candidates/{ProcessId}
Checking the status of the hire is needed, because failed hires won’t be automatically reprocessed. It is necessary to correct the problem and send them again.
Also it is possible to get a list of processes, filtering by status, created after and created before.
GET https://api.youserve.nl/recruiting/v1.0/candidates/status
GET https://api.youserve.nl/recruiting/v1.0/candidates/status?status=Completed
GET https://api.youserve.nl/recruiting/v1.0/candidates/status?createdAfter=2021-09-01&createdBefore=2021-09-12
Vacancies DRAFT
⚠️ This is a draft endpoint. Vacancy data cannot be exposed at this moment. Please reach out to our community for more info.
GET vacancies The endpoint GET vacancies gives a list of vacancies of the tenant. This endpoint is available only with mock data for the sandbox tenant.
GET https://api.youserve.nl/recruiting/v1.0/vacancies
Postman collection and environment
As attachment you can find a zip file with the collection and the environment.
... View more
Labels:
28-01-2022
11:25
This API is intended for external payroll systems and allows them to fetch the necessary data they need to run the payrolls.
Employee basic data
Property
Description
Example
Data type
isDeleted
If the employee was removed in the core system
true
boolean
customerId
The code of the tenant
4024898
string
companyId
The id of the company
15951
string
upi
The unique id assigned to the employee
32789
string
employeeCode
The code of the employee
1079224
string
employeeId
The employee id in the core system
13665966
string
contractId
The contract id in the core system
13665965
string
hireDate
The hire date of the contract
2017-03-01T00:00:00
DateTime
dischargeDate
The discharge date of the contract
2020-12-30T00:00:00
DateTime
personData
List of person data versions (*)
validFromDate
2017-03-01T00:00:00
DateTime
validToDate
2020-12-30T00:00:00
DateTime
personalDetails (name, lastname, birthdate, prefix...)
addresses (list of addresses (home and postal))
contactInformation (personal email, work email, work number...)
extensions
lastNameAtBirth
The last name at birth of the employee. Also known as the family name
Vries
string
prefixLastNameAtBirth
The prefix of the employee's last name at birth
de
string
lastNameToUse
The last name used by the employee at present
Vries - Van Eijck
string
prefixLastNameToUse
The prefix of last name used by the employee at present
Van
String
initials
The initials of the employee
A.B.
string
firstNames
The official given names of the employee
Amy Beatrice
string
knownAs
The name which is used by the employee as first name
Amy
string
titlePrefix
The title prefix of the employee
Mr.
string
titleSuffix
The title suffix of the employee
Jr.
string
gender
Gender of the employee
Female
string
dateOfBirth
The date of birth of the employee
1970-01-01
DateTime
dateDeceased
The date of the death
2020-01-01
DateTime?
countryOfBirth
The country of birth of the employee
ES
string
placeOfBirth
The place of birth of the employee
Amsterdam
string
maritalStatus
The marital status of the employee
1
string (reference list)
primaryNationality
The primary nationality of the employee
0001
string (reference list)
nationalIdentificationNumber
The national identification number of the employee
367565572
string
addresses
List of addresses
array of objects
type
Home
string
street
Kerkstraat
string
houseNumber
1
string
addition
C
string
additionalInfo
2nd floor
string
zipCode
1234 AB
string
city
Amersfoort
string
region
Region
string
country
NL
string (reference list)
contactInformation
emailAddresses
phoneNumbers
emailAddresses
List of email addresses
type
Private
string
address
p.user@example.com
string
phoneNumbers
List of phone numbers
type
Home
string
number
+3188 123 45 67
string
extensions
List of custom fields
key
AmountOfChildren
string
value
3
string
employmentData
List of employment versions (*)
validFromDate
2017-03-01T00:00:00
DateTime
validToDate
2020-12-30T00:00:00
DateTime
contractDetails
costAllocations
bankAccounts
workAmountPattern
extensions
contractNumber
The contract number
1
string
firstHireDate
The first hire date or original hire date of an employee within the organization.
2017-03-01T00:00:00
DateTime
location
The location of where the employment is being performed
Headquarter
string
contractType
The type of the contract
string
employmentType
Code of the employment type
4
string (reference list)
daysPeriod
Working days in a period for the employee
5
decimal
classification
Classification
110001
string (reference list)
jobProfile
The job profile code
DEV
string (reference list)
collectiveLaborAgreement
The collective labor agreement of the company
13124836
string (reference list)
organizationalUnit
The organizational unit of the employee
31081923
string (reference list)
terminationReason
The reason of the termination of the contract
REA
string (reference list)
costAllocations
List of cost allocations
costCenter
cc1
string
percentage
100
int
bankAccounts
List of bank accounts
country
NL
string (reference list)
iban
NL62INGB1954254121
string
accountOwner
string
bic
ABNANL2AALC
string
routingNumber
string
accountNumber
1954254121
string
bankName
string
bankAccountType
01
string (reference list)
currency
EUR
string (by default is EUR)
workAmountPattern
workingAmount
40
decimal
workingUnit
Hours
string
workingPeriod
1
string (reference list)
workPatternId
40HoursWeek
string
workingPatterns (list of work pattern versions that applies to the period of the contract version)
workingPattern
validFromDate
2017-03-01T00:00:00
DateTime
validToDate
2020-12-30T00:00:00
DateTime
days (list of workingDay)
workingDay
dayIndexNumber
1
int
dayOfWeek
Monday = 1
enum
hours
8
decimal
Dependents
List of dependents
dependentId
dependentPersonNumber
dependentData: List of dependent versions
dependentId
Identifier of the dependent
1
int
dependentPersonNumber
Person number of the dependent
10001
string
dependentData
List of dependent versions
prefix
Van
string
lastName
Vries
string
firstName
Erika
string
gender
Female
string
dateOfBirth
2001-01-01
DateTime
dateOfDeath
DateTime
relationship
Partner
string
relationshipStartDate
2020-01-01
DateTime
relationshipEndDate
2020-12-31
DateTime
validFromDate
2020-01-01
DateTime
validToDate
9999-12-31
DateTime
extensions: List of custom fields per dependent and country
(*) The list of versions of PersonData and ContractData includes all versions, when the employee is in service and out of service.
The extensions fields in PersonData, EmploymentData and DependentData would be filled in with custom fields.
No dependent data is available for German employees.
Employee benefits
Property
Description
Example
Data type
IsDeleted
If the employee was removed in the core system
true
boolean
customerId
The code of the tenant
4024898
string
employeeCode
The code of the employee
1079224
string
employeeId
The employee id in the core system
13665966
string
contractId
The contract id in the core system
13665965
string
Benefits
List of benefits of the employee
PayComponent
HourlySalary
string
value
20
string
validFrom
2017-03-01T00:00:00
DateTime
validTo
2020-12-30T00:00:00
DateTime
Pay components included as Benefits:
Pay component
Element number
KpiCompensation
10201240
PersonalAllowanceB
10201251
PersonalAllowanceC
10201252
PersonalAllowanceReduction
10201253
PersonalAllowanceIncludingCao
10201254
SightingFee
10201255
JobBonus
10201256
StandBy
10201257
CarAllowance
10201258
CostReimbursementTax
10201259
TravelExpenses
10204902
DivergentSalary
10300579
PersonalAllowancePercentage
10303254
HourlySalary
10518747
SalaryAmount
10302976
SalaryScale
10300574
SalaryLevel
10300575
CategorieSalaryScale
10300576
Employee fixed payments
Property
Description
Example
Data type
IsDeleted
If the employee was removed in the core system
true
boolean
customerId
The code of the tenant
4024898
string
employeeCode
The code of the employee
1079224
string
employeeId
The employee id in the core system
13665966
string
contractId
The contract id in the core system
13665965
string
FixedPayments
List of fixed payments of the employee
PayComponent
Fixed allowance
string
value
10
string
validFrom
2017-03-01T00:00:00
DateTime
validTo
2020-12-30T00:00:00
DateTime
Pay components included as Fixed payments:
Pay component
Element number
GrossFixedFee
10207320
InternshipCompensationNB
10207480
StaffBonus
10203907
ExpenseAllowanceUntaxed
10202687
BAdditionTaxableIncomeFixed
10207160
Employee one-off payments
Property
Description
Example
Data type
IsDeleted
If the employee was removed in the core system
true
boolean
customerId
The code of the tenant
4024898
string
employeeCode
The code of the employee
1079224
string
employeeId
The employee id in the core system
13665966
string
contractId
The contract id in the core system
13665965
string
OneOffPayments
List of one off payments of the employee
PayComponent
Train ticket
string
value
17
string
date
2017-03-01T00:00:00
DateTime
Pay components included as One Off Payments:
Pay component
Element number
DailyAllowenceNet01
10206880
DailyAllowenceNet02
10206882
DailyAllowenceNet03
10206884
DailyAllowenceNet04
10206886
DailyAllowenceNet05
10206888
DailyAllowenceNet06
10206890
DailyAllowenceNet07
10206892
DailyAllowenceNet09
10206896
DailyAllowenceNet10
10206898
DailyAllowenceNet11
10206900
DailyAllowenceNet12
10206902
DailyAllowenceNet13
10206904
KilometresStatement
10204904
CAllowenceVar
10200763
AAllowenceVar
10200759
Extensions fields for German companies
Person data extensions
Property
Example
Data type
SocialSecurityNumber
15090270W758
string
TaxIdentificationNumber
1234562001
string
Employment data extensions
Property
Example
Data type
CapitalAccumulationBenefits
2
string (reference list)
CertificationOfIncreasedPensionInsurance
2
string (reference list)
CertificationOfParenthood
2
string (reference list)
CertificationOfPensionInsuranceExemption
2
string (reference list)
ChildDaycareAllowance
2
string (reference list)
ChildTaxCredit
1
string (reference list)
CompanyCar
1
string (reference list)
CrossborderWorker
5
string (reference list)
DegreeOfDisability
9
string (reference list)
EducationDegree
1
string (reference list)
EmployeeGroup
1
string (reference list)
EmployerFundedPension
1
string (reference list)
HealthInsuranceType
3
string (reference list)
LevelOfEducation
9
string (reference list)
LimitedincomeTax
2
string (reference list)
MainEmploymentAtOtherEmployer
2
string (reference list)
Name
Audi BKK
string
Place
Ingolstadt
string
Religion
10
string (reference list)
TaxGroup
1
string (reference list)
TravelAllowance
1
string (reference list)
Vouchers
2
string (reference list)
With
3
string (reference list)
WorkingAs
71394-3
string (reference list)
WorkingLocation
HH
string (reference list)
ContractType
1
string (reference list)
Extensions fields for Belgian companies
Employment data extensions
Property
Description
Example
Data type
Element number in HRCB
LinkingTableBICCodeBelgium
Linking table bic code
2
string (reference list)
10525244
StartDateLimosaNotification
Effective date Limosa notification
2020-01-01
DateTime
10525245
NationalInsuranceNumberOld
National Insurance number (old)
750915 4998 658
string
10525231
LanguagePayslip
Salary slip language
1
string (reference list)
10525253
Flex
Flex
1
boolean
10525255
IncomePartner
Income of the partner
2
string (reference list)
10525252
CountryOfBirth
Country of birth
2
string (reference list)
10517302
EndDateLimosaNotification
End of limosa notification
2021-01-01
DateTime
10525246
NationalInsuranceNumber
INSZ number
750915 4998 659
string
10517301
DegreeOfEducation
Education degree
2
string (reference list)
10525254
MaritalStatusBE
Marital status
2
string (reference list)
10517075
TaxCivilStatusOnEmployment
Fiscal Marital status upon employment
1
string (reference list)
10519436
PrintPaySlips
Print payslips
1
boolean
7707
CategoryEmployee
Category of the employee
A
string (reference list)
10525264
ReasonForDismissal
Reason for dismissal
BP
string (reference list)
10525248
SeniorityDate
Seniority date
2020/08/14
DateTime
10525233
HierarchicalStatute
Hierarchical status
1
string (reference list)
10520266
TaxStatus
Tax status
1
string (reference list)
10525251
StartDateParentalLeave
Start date interruption parental leave
2021/01/01
DateTime
10525234
EndDateParentalLeave
End date interruption parental leave
2021/03/01
DateTime
10525235
ParentalLeave
Type interruption parental leave
OH
string (reference list)
10525257
PercentageInterruptionParentalLeave
Percentage interruption parental leave
12,00
number
10525237
StartDatePalliativeLeave
Start date interruption palliative leave
2021/01/01
DateTime
10525238
EndDatePalliativeLeave
End date interruption palliative leave
2021/03/01
DateTime
10525239
PalliativeLeave
Type interruption palliative leave
PD
string (reference list)
10525258
PercentagePalliativeLeave
Percentage interruption palliative leave
13,00
number
10525240
StartDateMedicalAssistance
Star date interruption medical assistance
2021/01/03
DateTime
10525241
EndDateMedicalAssistance
End date interruption medical assistance
2021/01/04
DateTime
10525242
MedicalAssistance
Type interruption medical assistance
MV
string (reference list)
10525259
PercentageMedicalAssistance
Percentage interruption medical assistance
14,00
number
10525243
StartDateTimeCredit
Start date interruption time credit
2021/01/05
DateTime
10525261
EndDateTimeCredit
End date interruption time credit
2021/01/06
DateTime
10525262
TimeCredit
Type interruption time credit
TV
string (reference list)
10525260
PercentageTimeCredit
Percentage interruption time credit
15,00
number
10525263
Contract1Type
Type of contract 1
1
string (reference list)
10525766
Contract2Type
Type of contract 2
2
string (reference list)
10525767
Contract3Type
Type of contract 3
3
string (reference list)
10525776
Contract1StartDate
Start date of contract 1
01/01/2021 00:00:00
DateTime
10525770
Contract2StartDate
Start date of contract 2
02/01/2021 00:00:00
DateTime
10525774
Contract3StartDate
Start date of contract 3
03/01/2021 00:00:00
DateTime
10525775
Contract1EndDate
End date of contract 1
01/31/2021 00:00:00
DateTime
10525771
Contract2EndDate
End date of contract 2
02/28/2021 00:00:00
DateTime
10525772
Contract3EndDate
End date of contract 3
03/31/2021 00:00:00
DateTime
10525773
NumberOfDependentChildren
Number of dependent children for tax purposes
1
int
10517103
NumberOfDependentHandicappedChildren
Number of disabled dependent children
1
int
10517104
PartnerIncome
Professional income partner
2
string (reference list)
10517076
HandicappedPartner
Disabled partner
1
boolean
10517102
HospitalizationInsuranceForPartner
Hospitalization insurance for partner
1
boolean
10526113
NumberOfDependentPersons
Number of other dependent residents <65 years
1
int
10517105
NumberOfDependentDependent
Number of other disabled residents dependent
1
int
10517106
NumberOfDependentPersonsGt65
Number of other dependents >= 65 years
1
int
10517107
NumberOfDependentHandicappePersonsGt65
Number of disabled residents dependent> 65 years
1
int
10517108
TaxRegimeBE
Belasting regime [BE]
10528135
SocialSecurityReductionReasonBE
Reden verlaging Sociale zekerheid [BE]
10528136
TaxReductionReasonBE
Reden belasting verlaging [BE]
10528137
SocialSecurityRegimeBE
Sociaal zekerheid regime [BE]
10528138
PartimeIndicationBE
Deeltijd indicatie [BE]
10528139
WorkScheduleNumberBE
Werkschema nummer [BE]
10528141
PaymentMethodBE
Betaalwijze [BE]
10528223
EmployeeContractBE
Arbeidsovereenkomst [BE]
10528224
GroupNumberBE
Groepsnummer [BE]
10528225
DentalInsurancePlus18BE
Dentalverzekering +18 [BE]
10528226
DentalInsuranceMinus18BE
Dentalverzekering -18 [BE]
10528227
NationalRegisterNumberProTimeBE
INSZ-nummer ProTime [BE]
10528228
EMailProTimeBE
E-mail ProTime [BE]
10528229
PartnerProfessioneBE
Beroep echtgenote [BE]
10528231
PeopleDependentOn65InformalCareBE
Personen ten laste 65+ mantelzorg [BE]
10528239
PersonsAtChargeDisabledPartnerBE
Pers. ten laste: Mindervalide echtgenote [BE]
10528240
PersonsAtChargePartnerBE
Personen ten laste-echtgenote [BE]
10528241
HigherValueMealVouchersBE
Hogere waarde maaltijdcheques [BE]
10528242
MonthlyGrossIncomeScaleBE
Barema brutoloon [BE]
10528243
HourlyWageScaleBE
Barema uurloon (chauffeurs) [BE]
10528244
SalaryLevelBE
Looncategorie [BE]
10528245
HourlyWageBE
Basis uurloon arbeiders [BE]
10528246
MonthlyGrossIncomeBE
Maandloon bedienden [BE]
10528247
AlternativeHourlyWage2BE
Basis uurloon chauffeurs [BE]
10528248
ReasonWageIncreaseBE!!
Reden loonsverhoging [BE]
10528249
ExtraAllowance1BE
Distributiepremie chauffeurs [BE]
10528250
ExtraAllowance2BE
Toeslag trainer chauffeurs [BE]
10528251
WorkSchemeCodeBE
Werkschema code [BE]
10528252
DisabledEmployee
Minder valide medewerker
10528253
TypeOfPayslipBE
Type loonstrook [BE]
10528254
Regime5Or6BE
Stelsel 5-6 [BE]
10528259
BirthcountryBE
Geboorteland [BE]
10528257
Nationality
Nationaliteit
10519287
CountryBE
Woonland [BE]
10528256
FunctionLevelBE
Functieniveau [BE]
10528456
DepartureReasonBE
Reden ontslag [BE]
10528258
HospitalisationInsurancep18
Hospitalisatieverzekering +18 [BE]
10528431
HospitalisationInsurancem18
Hospitalisatieverzekering -18 [BE]
10528432
WorkLocation
Work Location
7449
LastNameToUse
Last name to use
590
NumberOfPeopleDependentOn65PlusInformCare
Number of people dependent 65+ on informal care
10528515
Dependent data extensions
Property
Description
Example
Data type
Element number in HRCB
DependentPersonStatus
Status
1
string (reference list)
10519335
DependentPersonIsDisabled
Disabled
1
boolean
10519251
HospitalizationInsuranceForChild
Hospitalization insurance for a child?
1
boolean
10526114
DisabilityRate
Disability rate
50
decimal
10526116
IsChildBenefitReceived
Are child benefits received?
1
boolean
10526115
*For employees with a large amount of versions that cannot be stored, the solution is to remove the older versions until it fits in the storage structure.
... View more
Labels:
28-01-2022
11:25
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.
... View more
Labels:
28-01-2022
11:24
The Learning API is intended for Learning Management systems and allows you to:
Read employees and organizational structures from Youforce to update the learning system
Upload certificates to the Youforce Personal File system of the customer
Domain model
Concepts
Employees
The object employee contains all personal and employment details of an employee.
Object attributes
An employee is a person with one or more employments.
Attributes person details
Attribute
Description
id
Unique id for the Person row within the tenant
personCode
The logical person code of the employee
Initials
The initials of the employee.
firstNames
The official given names of the employee as stored in the HR Core system
KnowAs
The name which is used by the employee as his first name
lastNameAtBirth
The last name at birth of the employee. Also known as the family name
lastNameAtBirthPrefix
The prefix of the last name at birth
lastName
The last which is currently used by the employee as his last name
lastNamePrefix
The prefix of the last name as used currently
nameAssembleOrder
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.
partnerName
The partner last name
partnerNamePrefix
The prefix of the partner last name
titlePrefix
The formal title which will be used as a prefix before the name like Doctor, Professor, et cetera
titleSuffix
The formal title which will be used as postfix after the name like MSc or Master of Science
gender
Gender of the person. Supported values are Male / Female. Note: other type of genders will be shown as Not Known
birthDate
Date of birth
deceased
Indicated if the employee deceased
UserUID
Digital Identity of the user from the portal
emailAddresses
type
address
List of the addresses of the employee. The fields are:
type like Business, Private, et cetera
address
Addresses
type
street
houseNumber
houseNumberAdditional
locationDesignation
postalCode
city
region
country
List of the addresses of the employee. The fields are:
type like Home, Post, et cetera
street name
house number
house number additional
Location designation
Postal code
City
Region
Country code
phoneNumbers
type
number
list of phone numbers of the employee
type like Business, Home, Mobile, et cetera
number
communicationLanguage
Communication language
Attribute employment details
Attribute
Description
employeeID
Technical and unique id. the Id is unique within the entity and tenant.
employeeCode
Code of the employee
employmentCode
Logical code of the employment
company
Unique (alphanumeric) identifier of the company with which the contract is concluded
hireDate
The hire date of the employment
dischargeDate
The end date or discharge date of the employment.
originalHireDate
The first hire date or original hire date of an employee within the organization.
employmentType
Type of employment with a short name for type like Internal employee, contractor, "Wachtgelder"
jobProfile
job profile code of the employment The job profile is a code that refers to the entity job profile
organizationUnit
organization unit of employment. The organization unit is a code that refers to the entity organization units
workingAmount
amountOfWork
unitOfWork
periodOfWork
Work amount of employment.
The amount of work
Unit of work that specifies the amount of work like "hours", "days", et cetera
Period of work like "week" or "month"
contractType
Contract type of the employee. It is the code that refers to the entity contract type.
costCenter
Main cost center associated with the employee. It is the code that refers to the entity cost center.
classification
Classification of the employee. It is the code that refers to the entity Classification.
location
Location of the employee. It is the code that refers to the entity location.
salaryScale
Salary scale of the employee. It is the code that refers to the entity salary scale
establishmentUnit
Establishment unit of the employee.
Data mapping
Attributes person details
attribute
HR Core Business
personId
Technical id of the employee in HRCB
personCode
7014 - Uniek Persoonlijk ID (UPI) (If it is not filled in then the Medewerkercode - 22)
Initials
25 - Voorletters
firstNames
51 - Voornamen
KnowAs
165 - Roepnaam
lastNameAtBirth
24 - Achternaam
lastNameAtBirthPrefix
26 - Voorvoegsel
lastName
524 - Opgemaakte naam aanhef Note: In HRCB this field is combination of the last name and the last name prefix
lastNamePrefix
#NA
nameAssembleOrder
28 - Eigennaam code
partnerName
27 - Naam Partner
partnerNamePrefix
166 - Voorvoegsel Partner
titlePrefix
94 - Titel voor
titleSuffix
95 - Titel na
gender
36 - Geslacht
Mapping details: 1 or Man → Male 2, Vrouw, Woman → Female Other values will shown as Not Known
birthDate
35 - geboorte datum
deceased
Based on the date of deceased. If the employee is deceased the boolean is set to True 10302568 - Datum overlijden
UserUID
10523564 - PING ID
emailAddresses
type
address
Business : 7212 - E-mailadres Prive: 7213 - E-mailadres Prive
Addresses
type
street
houseNumber
houseNumberAdditional
locationDesignation
postalCode
city
region
country
Home:
391 - straat 392 - Huisnummer 393 - Huisnummer toevoeging
8099 - Locatie omschrijving
394 - Postcode 395 - Woonplaats 34 - Woonland
10205283 Regionaam Buitenland
Postal:
7572 - Straat Postadres 7573 - huisnummer Postadres 7574 - Huisnummer toev. adres
8100 Locatie omsch Postadres 7575 - Postcode Postadres 7576 - Plaats Postadres 7571 - Land
8101 Regionaam Buitenland
phoneNumbers
type
number
Home : 7376 - Telefoonnummer prive Mobile : 7377 - Telefoonnummer mobiel Business : 7374 - Telefoonnummer intern
addresses
communicationLanguage
10
Attribute employment details
Attribute
HR Core Business
employeeID
technical ID of the employee in HRCB
employeeCode
22 - Medewerkercode
employmentCode
91 - contract ID
company
18 - company code
hireDate
39 - Datum indienst
dischargeDate
10520479 - Geplande laatste datum indienst
originalHireDate
308 - Datum indienst organisatie
employmentType
7393 - Type Medewerker
jobProfile
97 - functie
organizationUnit
6000 - Organisatorische eenheid
workingAmount
amountOfWork
unitOfWork
periodOfWork
amount of work = 465 - Uren periode
perodOfWork = 463 - Dagen / uren per
*HRCB supports only amount of work in "hours" parttimePercentage is not available
contractType
contract type = 10204687
costCenter
cost center = 53
classification
classification = 474
location
location = 75
salaryScale
salaryScale = 10300574
establishmentUnit
establishmentUnit = 7449
Users
The object User contains the User Identity for Single Sign-On. The User Identity is stored in the User Management System of the Youforce portal and can be used to support Single Sign-On.
For HR Core Business the User Identity is already part of the employee endpoint.
Object attributes
attribute
example
description
id
c7e230db-2a7f-4ef0-ad1d-9d30e7d94a2f
User Identity of the employee for Single Sign On.
sourceId
XX123456
not relevant within the learning domain
identityId
null
not relevant within the learning domain
Organization units
The object Organization Units will provide all HR Data regarding the organization structure, like business Unit, department. Next to that, it describes in what way these are related to each other. Based on the organizational structure it’s clear ‘which' department is responsible for 'what’.
Object attributes
The organization unit and the role assignment how the organization is structured and who is responsible in which role.
Attributes Organization Unit
Attribute
Description
id
Unique Id of the organization Unit
shortName
Logical code of the organization Unit
fullName
Logical name of the organization Unit
parentOrgUnit
Id of the parent organization Unit In some core systems this relation can changed in during the timeline of an organization Unit.
organizationUnitType
Type of organization Unit
manager
Manager of the organization unit
managerPersonCode
Person code of the manager
backupManager
Backup manager of the organization unit
backupManagerPersonCode
Person code of the backup manager
Attributes Role Assignment
Attribute
Description
id
Unique Id of the record
OrganizationUnitId
Id of the organization unit the role assignment is effective for
roleCode
Code of the role. For instance the role manager is identified with the role code MGR.
personCode
Person who have this role for the specific organisation unit. The person code is a reference to the Person code in the employee
personId
Person who have this role for the specific organisation. The person id is a reference to the Person id in the employee table
startDate
Start date from which the role assignment is valid for that employee
endDate
End date from which the role assignment is valid for that employee
Data mapping
Attributes Organization Unit
Attribute
HR Core Business
id
Technical id from HRCB
shortName
548 - code OE
fullName
549 - Naam OE
parentOrgUnit
technical id of the parent Org unit
organizationUnitType
#N/A
managerId
7137 - manager
Attributes Role Assignment
Attribute
HR Core Business
id
Technical id from HRCB
OrganizationUnitId
548 - code OE
roleCode
549 - Naam OE
personCode
#N/A
personId
Reference to the Person Id
startDate
#N/A
endDate
#N/A
Job profiles
Object attributes
The object job profile contains the following attributes.
Attribute
Description
shortName
short name of the job profile
fullName
full name of the job profile
jobFamily
job family to which the job belongs.
Data mapping
Attribute
HR Core Business
shortName
Functie code
fullName
functie naam
jobFamily
Job family
Companies
Object attributes
The object company contains the following attributes.
Attribute
Description
id
identifier of the company
code
company code
fullName
full name of the company
ValidFrom
Start date of the version of the company
ValidUntil
End date of the version of the company
Data mapping
Attribute
HR Core Business (Supported level: Client)
id
mutkey
code
company code
fullName
company name
Contract types
Object attributes
The object contract type contains the following attributes.
Attribute
Description
code
contract type code
fullName
full name of the contract type
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: System)
code
contract type code
fullName
contract type name
Employment types
Object attributes
The object employment type contains the following attributes.
Attribute
Description
code
employment type code
fullName
full name of the employment type
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: Client)
code
employment type code
fullName
employment type name
Cost centers
Object attributes
The object cost center contains the following attributes.
Attribute
Description
code
cost center type code
fullName
full name of the cost center
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: Client)
code
cost center code
fullName
cost center name
Classifications
Object attributes
The object classification contains the following attributes.
Attribute
Description
code
classification code
fullName
full name of the classification
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: Client)
code
classification code
fullName
classification name
EstablishmentUnits
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 Learning API, the work location is known as establishmentCode. The establishmentCode is delivered with Employees:
Employees.Contracts.establishmentCode = EstablishmentUnits.Code
The object classification contains the following attributes.
Attribute
Description
code
code of work location
name
full name of the work location
ValidFrom
Start date of the version
ValidUntil
End date of the version
numberKvk
Number of chamber of commerce
phoneNumber
phone number
emailAddress
email address
address.description
Address information
address.street
address.houseNumber
address.houseNumberSuffix
address.postalCode
address.city
address.country
MailingAddress.locationDescription
Postal Address information
MailingAddress.street
MailingAddress.houseNumber
MailingAddress.houseNumberSuffix
MailingAddress.postalCode
MailingAddress.city
MailingAddress.country
Data mapping
Attribute
HR Core Business
code
548 - Code (refers to Employees.employments.
establishmentUnit
name
7445 - name of work location
ValidFrom
ValidUntil
numberKvk
7271 - Number KvK
phoneNumber
7415 - phone number
emailAddress
7447 - Email address of work location
address.description
8099 - work location description
address.street
7454 - Street
address.houseNumber
7451 - house number
address.houseNumberSuffix
7452 - house number suffix
address.postalCode
7453 - postal code
address.city
7446 - city
address.country
8110 - country
MailingAddress.locationDescription
8100 - description of location
MailingAddress.street
7383 - street
MailingAddress.houseNumber
7380 - house number
MailingAddress.houseNumberSuffix
7384 - house number suffix
MailingAddress.postalCode
7382 - postal code
MailingAddress.city
7381 - city
MailingAddress.country
7571 - country
Locations
Object attributes
The object location contains the following attributes.
Attribute
Description
code
location code
fullName
full name of the location
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: Client)
code
location code
fullName
location name
Salary scales
Object attributes
The object salary scale contains the following attributes.
Attribute
Description
code
salary scale code
fullName
full name of the salary scale
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: Client)
code
salary scale code
fullName
salary scale name
Job families
Object attributes
The object job family contains the following attributes.
Attribute
Description
code
job family code
fullName
full name of the job family
ValidFrom
Start date of the version
ValidUntil
End date of the version
Data mapping
Attribute
HR Core Business (Supported level: System)
code
job family code
fullName
job family name
File upload
With the documents endpoint files, certificates and other documents can be uploaded for an employee to the Visma Personal File System (Personeelsdossier).
Asynchronous file upload
Learning systems can upload files, like certificates, diplomas for individual employees to the Personal File System of Visma Raet. The file upload is an a-synchronized process. After the file is uploaded the consumer will receive a ticket Id, which can be used to monitor the process of the file upload.
... View more
Labels:
28-01-2022
11:24
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
EstablishmentUnits (Work location) - (NEW September 2025)
GET establishmentunits
The endpoint GET establishmentunits gives a list of work locations. https://api.youserve.nl/learning/v1.0/establishmentunits
Retrieve only records which that have changed within the provided date-time (UTC) range:
GET https://api.youserve.nl/learning/v1.0/establishmentunits?from=2025-01-01T09:00:00.000Z&to=2025-06-30T14:00:00.000Z . Format: YYYY-MM-DDTHH:MM:SS.sssZ.
Get stablishmentunits by id
The endpoint GET establishmentunits by id gives a list of all the versions of the work location with the given id.
https://api.youserve.nl/learning/v1.0/establishmentunits/<id>
Get stablishmentunits by code
The endpoint GET establishmentunits by code gives a list of all the versions of the work location with the given code.
https://api.youserve.nl/learning/v1.0/establishmentunits?code=101
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.
*For uploading certificates correctly, configuration by the consultants is needed.
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.
... View more
Labels:
28-01-2022
11:23
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.
... View more
Labels:
28-01-2022
11:22
15-09-2025: new endpoint: EstablishmentUnits
We have added a new endpoint to the Learning API: EstablishmentUnits.
The EstablishmentUnits endpoint delivers the work locations of an organization registered in HR Core.
This new functionality is now accessible to all Learning API users, without reloading the data.
For detailed information about the new functionality, please refer to our knowledge base:
EstablishmentUnits properties
EstablishmentUnits endpoints
2020-08-20 - API enhancements
The following enhancements are now available:
Record versions (validFrom / validUntil) in all endpoints
With this release we we support record version in every endpoint. Even if the the Core system doesn’t support record versioning, like HR Core Beaufort, we add default value for the validFrom and ValidUntil attributes. The default for ValidFrom is '0001-01-01' and the default validUntil is '9999-12-31'.
Delete flag for delete records
If a record is deleted in the core system, a isDelete = true attribute is set in the API. Based on this information you can delete the record as well in your own system.
Delete means that the whole entity is deleted and not just one version.
"id": "907624", "isDeleted": true, "shortName": "907624" } ]]>
Note:
Delete means that we delete the whole record and not just a version.
ID attribute in Job profile was missing
In the Job Profile endpoint an ID was missing. In this release we add the ID field to the Job Profile as well. For Job profile the ID and shortName contains both the same value.
Example of the ID and the validFrom and validUntil in the Job profile endpoint
{ "id": "723912", "shortName": "723912", "fullName": "Business Analyst", "jobFamily": "Software", "validFrom": "0001-01-01", "validUntil": "9999-12-31" } ] ]]>
Manager in organization Unit endpoint (HRCB Business only)
For HR Core Business the manager was missing in the organization unit endpoint. In this release we add the manager field to the organization unit endpoint.
Note:
For HR Core Beaufort the manager is part of the endpoint role assignment with role type = MGR
UserUID for Single Sign On as part of the employee endpoint
In this release we add the userUID as part of the employee endpoint. The userUID can be used for the Single Sign On solution of Visma Raet.
{ "id": "79500", "personCode": "79500", "initials": "HJB", "firstNames": "Herbert Jacob Bert", "knownAs": "Herbert", "lastName": "Robles", "lastNameAtBirth": "Robles", "nameAssembleOrder": "E", "gender": "Male", "birthDate": "1989-03-02", "deceased": false, "userUID": "3d89f34f-9fd8-41c4-8d63-09051a470591", "employments": [ { "employmentCode": "1", "hireDate": "2020-01-01", "employmentType": "005", "originalHireDate": "2020-01-01", "jobProfile": "8302", "organizationUnit": "1867", "workingAmount": { "amountOfWork": 36, "unitOfWork": "Hours", "periodOfWork": "Week" } } ], "validFrom": "1900-01-01", "validUntil": "9999-12-31" }]]>
2020-08-19 - Employee endpoint includes also address details and original hire date
The address details and the original hire date are also added to the employee endpoint.
"id": "79505", "personCode": "79505", "initials": "J", "firstNames": "Jos", "knownAs": "Josje", "lastName": "Janssens", "lastNameAtBirth": "Janssens", "nameAssembleOrder": "E", "gender": "Female", "addresses": [ { "type": "Home", "street": "Computerweg", "houseNumber": "99", "postalCode": "3822CM", "city": "AMERSFOORT", "country": "NED" }, { "type": "Postal", "street": "Computerweg", "houseNumber": "99", "postalCode": "3822CM", "city": "AMERSFOORT", "country": "NED" } ]]>
2020-07-01 - Learning API Controlled available
The Learning API is controlled available. The API supports endpoints for:
Getting employee data from HR Core systems like HR Core Beaufort and HR Core Business
Upload diplomas or certificates to the Personal File System of Visma Raet (Personeelsdossier)
2021-03-23 - Uploading certificates for HRCB customers is available
Uploading certificates in the Learning API was previously working only for HR Core Beaufort customers. Now is also available for HRCB customers.
2021-03-29 - Job family code in job profile
The job family code is now available as part of the job profile data.
2021-04-08 - Performance improvements
Performance improvements in queries.
2021-04-16 - Job familiy reference list is available
The endpoint for getting the job family reference list is available.
2021-05-05 - Fixed issue with the changedUntil parameter
The changedAfter parameter can be used now without the changedUntil parameter. Search with the changedUntil parameter is working now without the changeAfter parameter.
2022-03-16 Communication Language added as part of employee data
The communication language is now available as part of the employee data.
2024-02-27 Manager person code added as part of Organizational Unit
The manager person code is now available as part of the organizational unit data.
2025-03-04 Backup manager id and backup manager person code added as part of Organizational Unit
The backup manager id and backup manager person code are now available as part of the organizational unit data.
Please read the documentation and the FAQ if you have questions about “How to use this API”.
... View more
Labels:
Activity Feed for Carmen Martínez
- Posted HR Core and Payroll API - Release notes on Releases YouServe API's. 28-02-2025 15:39
- Posted Payroll API - Release notes on Releases YouServe API's. 23-01-2025 19:03
- Posted Recruiting API - Release Notes on Releases YouServe API's. 24-06-2024 20:20
- Posted HR Core and Payroll API - Endpoints on Knowledge base YouServe API's. 10-10-2023 12:17
- Posted HR Core and Payroll API - Domain model and concepts on Knowledge base YouServe API's. 09-10-2023 10:36
- Posted Payroll API - Release Notes & highlights on Releases YouServe API's. 19-05-2023 17:13
- Posted Recruiting API - Domain model and concepts on Knowledge base YouServe API's. 28-01-2022 11:26
- Posted Recruiting API - Endpoints on Knowledge base YouServe API's. 28-01-2022 11:26
- Posted Payroll API - Domain model and concepts on Knowledge base YouServe API's. 28-01-2022 11:25
- Posted Payroll API - Endpoints on Knowledge base YouServe API's. 28-01-2022 11:25
- Posted Learning API - Domain model and concepts on Knowledge base YouServe API's. 28-01-2022 11:24
- Posted Learning API - Endpoints on Knowledge base YouServe API's. 28-01-2022 11:24
- Posted Learning API - FAQ on Knowledge base YouServe API's. 28-01-2022 11:23
- Posted Learning API - Release Notes on Releases YouServe API's. 28-01-2022 11:22
Useful pages
Contact us
Copyright © 2022 Visma.com. All rights reserved.
Visma Finland
Visma Latvia
Visma Netherlands
Visma Norway
Visma Sweden
Visma Developers & Partners
Visma Latin America