POST /users
Request parameters (without employments)
Parameter | Type | Description |
---|---|---|
id | string | If provided existing user will be edited. If not provided a new user will be created. |
accountId | string | Provide this id if existing user should be edited. |
accountRelId | long | Provide this id if existing user should be edited. |
parentGroupRelId | long | Provide this id if existing user should be edited. |
historyDataId | string | Provide this id if existing user should be edited. |
firstName | string | Users first name. |
lastName | string | Users last name. |
string | If provided when adding new user, then an email invite for users confirmation will be sent to user. If provided when editing existing user, then email will be changed directly. | |
validFrom | date | Date from which the user can log in and use the application. Provide date in ISO-8601 and UTC format with +00:00 time zone, eg. 2022-01-01T00:00:00+00:00 |
validTo | date | Date until user can log in and use the application. If this date is in past user will be treated as inactive. Provide date in ISO-8601 and UTC format with +00:00 time zone, eg. 2022-12-31T23:59:59+00:00 |
gender | string | Possible values: "male", "female", "none" |
mobilePhoneNumber | string | If provided then SMS notifications can be sent via the application. |
nationality | string | If desired, provide "country" from Country List. |
birthDate | date | If desired, provide Users birth date in ISO-8601 YYYY-MM-DD format, eg. 1990-10-22 |
availableLoginMethods | array [integer] | Provide "0" if user is allowed to login in the web application only. Provide "1" if user is allowed to login in the mobile applications only. Provide "0" and "1" if user is allowed to login in web and mobile applications. Provide "-1" if user is not allowed to login at all. If no information is provided then "0" and "1" will be saved. |
address | object | If desired an address can be saved. |
relID | long | Provide this id if existing user should be edited. |
id | string | If provided existing address will be edited. If not provided a new address will be created. |
street | string | Street of the address. |
city | string | City of the address. |
state | string | State of the address. |
postalCode | string | Postal code (zip) of the address. |
country | string | If desired, provide "country" from Country List. |
exportIds | object | If desired, up to three export id's can be used to match user with third party applications. |
exportId1 | string | If needed provide an export id. |
exportId2 | string | If needed provide an export id. |
exportId3 | string | If needed provide an export id. |
hardwareTerminalChipId | string | Provide a chip id of users hardware terminal, if available. |
roles | array [object] | Provide an array of roles where user should get the role assigned. If no array is provided then user will be assigned as "employee" role to the main organization (company). |
role | string | Possible roles: "employee", "approver", "manager", "administrator", "main_administrator" |
organizations | array [object] | Provide "id" where user will get the role assigned. Only one assignment at time is possible. |
relId | long | Provide this id if existing user should be edited. |
name (organizations) | string | Name of organization where user will get the role assigned. |
id (organizations) | string | Mandatory fieled. Provide id of organization where user will get the role assigned. |
Request parameters (describing only "userEmployments" object)
Add or Edit User Employments
Parameter | Type | Description |
---|---|---|
userEmployments | array [object] | If desired an array of user employment objects can be created during same POST call. |
id | string | If provided existing user employment will be edited. If not provided a new user employment will be created. |
basicData | object | |
employmentStart | date | Date of employment start. Provide in ISO-8601 and UTC format with +00:00 time zone, eg. 2022-01-15T00:00:00+00:00. If not provided today's date will be saved. |
employmentEnd | date | Date when employment ended. Provide in ISO-8601 and UTC format with +00:00 time zone, eg. 2022-01-31T23:59:59+00:00. "employmentStart" and "employmentEnd" dDates may not overlap with other existing employment dates. |
comment | string | Comment attached to employment. |
employeeId | string | Employee's ID. |
employmentId | integer | Employee's employment ID. |
employmentRelationship | string | Possible values: "worker", "employee", "managing_director", "apprentice_worker", "apprentice_employee", "official", "asylum_seekers", "civilian_servants", "retrainee_rehabilitants_worker", "retrainee_rehabilitants_employee", "minimum_security", "other_persons_without_health_insurance_protection" |
dismissReason | string | Possible values: "notice_from_employer", "notice_from_employee", "mutual_notice", "time_expired", "eligible_early_leave", "dismissal_without_notice", "maternity_leave_acc_mschg_1979_vkg", "military_service", "civilian_service", "tenure_track_leave", "longer_than_one_month_unpaid_vacation", "register_change", "death_of_the_employee", "change_in_sv", "military_exercise", "retirement", "end_of_free_contract_acc_par_4_abs_4_asvg", "supersession_of_tribunal_service", "interruption_of_tribunal_service", "dismissal_from_federal_care", "notice_from_employee_while_parental_leave_acc_mschg_1979_vkg", "ineligible_early_leave", "study_leave_acc_par_11_avrag", "early_leave_from_employee_acc_parr_25_io", "notice_acc_par_25_io_from_insolvency_administrator", "notice_acc_par_25_io_from_employer", "end_of_sv_employment_active", "end_in_trial_time_through_employer", "study_leave_acc_par_12_avrag", "end_in_trial_time_through_employee", "other_exit_reason", "mutual_notice_because_of_transfer_to_employer" |
openVacationDays | double | Employee's open vacation days after employment's end. |
outstandingHours | double | Employee's outstanding hours or overtimes after employment's end. |
paySchedules | array [object] | Provide an object of pay schedule id's to which users employment will be assigned. |
id | string | ID of pay schedule to which users employment will be assigned. |
insuranceInformation | object | |
healthInsuranceCountry | string | Employee's health insurance country. If desired, provide "country" from Country List. |
healthInsuranceNumber | string | Employee's health insurance number. |
tariffGroup | string | Employee's tariff group. |
typeOfHealthInsurance | string | Possibile values: "statutory", "private" |
healthInsuranceCompany | string | Name of health insurance company. |
employmentContract | object | |
position | string | Employee's position. |
employmentType | string | Possibile values: "full_time", "part_time", "marginally", "daily", "independent_contractor", "apprenticeship", "intern", "parent", "inactive", "part_time_student", "other" |
weeklyHours | double | Employee's weekly working hours. |
probationPeriod | date | Employee's probation period. Provide in ISO-8601 and UTC format with +00:00 time zone, eg. 2022-02-15T00:00:00+00:00 |
periodOfNotice | string | Employee's period of notice. |
collectiveAgreement | object | Employee's collective agreement data, if applicable. |
collectiveAgreementId | integer | |
collectiveAgreementName | string | |
usageGroup | string | |
publicProfile | object | Employee's public profile data, if applicable. |
office | string | |
department | string | |
costCenter | string | |
workPhone | string | |
hrInformation | object | Employee's HR information, if applicable. |
status | string | Possible values: "active", "inactive", "dormant" |
superVisorUserId | string | User ID of employee's supervisor. |
hrContactUserId | string | User ID of employee's HR contact person. |
payrollInformation | object | Employee's payroll information, if applicable. Some country specific data may not be needed in certain countries. |
taxIdentificationNumber | string | |
taxOfficeId | integer | |
taxClass | integer | Possible values: "1", "2", "3", "4", "5", "6" |
localAuthorityId | integer | |
workplaceId | integer | |
wageTaxAllowance | double | |
maritalStatus | string | Possible values: "single", "married", "single_parent", "widowed" |
denomination | string | |
childBenefit | double | |
dependants | integer | Possible values: "0" for not applicable, "1" for one child, "2" for two children, "3" for three children, "4" for four children |
childRelief | double | |
severeDisability | boolean | Possible values: "true", "false" |
disability | string | |
highestGraduation | string | |
highestOccupation | string | |
buak | boolean | Possible values: "true", "false" |
occasionallyEmployed | boolean | Possible values: "true", "false" |
employmentBenefits | boolean | Possible values: "true", "false" |
commuterAllowance | integer | |
subwayTax | boolean | Possible values: "true", "false" |
municipalTax | boolean | Possible values: "true", "false" |
overtimeSettings | object | Employee's overtime settings, if applicable. |
showCompensationAccount | boolean | Possible values: "true", "false" If true is selected, then the employee will be able to view their time compensation account in applikation, otherwise they will not. |
compensationMultiplier | double | All overtimes (target time differences) are multiplied by this multiplier and displayed on the time compensation account. Negative values are allowed. [required]if showCompensationAccount = true |
compensationCorrection | double | Number of hours to be transferred and added to the time compensation account. Negative values are allowed. |
onlyApprovedEntries | boolean | Possible values: "true", "false" If true is selected, then only time entries that have been approved will be taken into account. If false is selected, then every time entry will be taken into account except rejected ones. [required] if showCompensationAccount = true |
vacationSettings | object | Employee's vacation settings, if applicable. |
showVacationAccount | boolean | Possible values: "true", "false" If true is selected, then the employee will be able to view their vacation account, otherwise they will not. |
vacationYearStart | date | Provide date in ISO-8601 and UTC format with +00:00 time zone, eg. 2022-01-01T00:00:00+00:00 at which a new vacation entitlement is calculated each year. [required] if showVacationAccount = true |
workDaysInWeek | double | Number of weekdays on which the employee works. For example, 5, if the employee works from Monday to Friday. [required] if showVacationAccount = true |
vacationWeeksPerYear | double | Number of vacation weeks per year. [required] if showVacationAccount = true |
totalVacationDaysPerYear | double | Vacation Entitlement In Weeks Per Year workDaysInWeek * vacationWeeksPerYear if NULL value provided |
oldVacationDays | double | Select the number of vacation days to be transferred and added to the vacation account. Negative values are allowed. |
correctionDays | double | Any number of days can be entered which will be added to the vacation account. Negative values are allowed. |
onlyApprovedDays | boolean | Possible values: "true", "false" If true is selected, then only vacation days that have been approved will be taken into account. If false is selected, then every vacation entry will be taken into account except rejected ones. [required] if showVacationAccount = true |
bankDetails | Employee's bank information details. | |
paymentType | string | Possible values: "cash", "credit", "bank_transfer" |
nameOfAccountHolder | string | |
iban | string | |
bicSwift | string | |
bankName | string |
Simple request JSON example
A user will be created if either an "email" is provided OR "firstName" OR "lastName".
{
"email": "[email protected]"
}
Warning
If user "id" is sent in request, then existing user will be edited.
If in such a case the request JSON has NULL values (because some attributes are not sent at all), then all objects with NULL values will be removed.When updating a user, then make sure that already saved data is sent in request again in order to avoid deleting this data.
Full request JSON example (with one employment):
{
"id": "3d6bf9bf-f27a-46f4-bbe5-ab717999f5d5",
"validFrom": "2023-01-01T00:00:00+00:00",
"validTo": "2024-03-31T00:00:00+00:00",
"firstName": "John",
"lastName": "Doe",
"email": "none",
"accountId": "cfdb8f2c-6b42-4c8a-9dd6-25878519dff5",
"gender": "male",
"mobilePhoneNumber": "+4366412345678",
"nationality": "AT",
"birthDate": "1985-2-1",
"availableLoginMethods": [
2
],
"roles": [
{
"role": "employee",
"organizations": [
{
"id": "d621f799-d190-40b6-8ee8-b3f38d5b1403",
"name": "Test Prod GmbH",
"relId": 2545326,
"validFrom": "2023-01-01T00:00:00+00:00",
"validTo": "2024-03-31T00:00:00+00:00"
}
]
}
],
"address": {
"id": "8d75c226-27e4-4542-9d7e-f5c6a92a1bf2",
"street": "Teststraße 123",
"city": "Graz",
"state": "Steiermark",
"postalCode": "12345",
"country": "AT",
"relId": 2545315
},
"exportIds": {
"exportId1": "123",
"exportId2": "456",
"exportId3": "789",
"hardwareTerminalChipId": "999"
},
"userEmployments": [
{
"id": "a94a5dfb-d5cb-4fb7-ba6c-1fc4c57b4edf",
"from": null,
"to": null,
"validFrom": null,
"validTo": null,
"paySchedules": [],
"basicData": {
"id": null,
"employmentStart": "2023-12-04T00:00:00+00:00",
"employmentEnd": "2200-01-01T00:00:00+00:00",
"comment": "Test Comment",
"employeeId": "1",
"employmentId": 2,
"employmentRelationship": "employee",
"dismissReason": null,
"openVacationDays": null,
"outstandingHours": null
},
"insuranceInformation": {
"id": "328fb901-f317-4978-a4ed-ac277d5e3fc1",
"healthInsuranceCountry": "AT",
"healthInsuranceNumber": "1234121212",
"tariffGroup": "Tariff 123",
"typeOfHealthInsurance": null,
"healthInsuranceCompany": "Insurance Corp."
},
"employmentContract": {
"position": "Metallworker",
"employmentType": "full_time",
"weeklyHours": 40.0,
"probationPeriod": "2024-02-29T00:00:00+00:00",
"periodOfNotice": "14 days"
},
"collectiveAgreement": {
"id": "b7661353-a4cb-478d-9ae6-52647394848b",
"collectiveAgreementId": 987,
"collectiveAgreementName": "EMG KV",
"usageGroup": "VW 123"
},
"publicProfile": {
"office": "Wien",
"department": "HR",
"costCenter": "123",
"workPhone": "0123456789"
},
"hrInformation": {
"id": "a0027d58-0473-43fd-8fb8-b66cdef64ff0",
"status": "active",
"superVisorUserId": "ff0c329d-d8f4-4658-ae39-9506bc900c14",
"hrContactUserId": "4c970f18-c5e9-4c81-a676-e28240bc4635"
},
"payrollInformation": {
"id": "3f40c01f-1207-4b43-9a36-4a66661a2a15",
"taxIdentificationNumber": "AT123",
"taxOfficeId": 9876,
"localAuthorityId": 1234,
"workplaceId": 5678,
"taxClass": null,
"wageTaxAllowance": 1200.0,
"maritalStatus": "married",
"denomination": "Test",
"childBenefit": 123.0,
"dependants": 2,
"childRelief": 500.0,
"severeDisability": false,
"disability": "Test",
"highestGraduation": "Matura",
"highestOccupation": "Test",
"buak": false,
"occasionallyEmployed": false,
"employmentBenefits": true,
"commuterAllowance": 123,
"subwayTax": true,
"municipalTax": true
},
"overtimeSettings": {
"id": "231b9d9e-fbde-47b7-90da-933758c05bef",
"showCompensationAccount": true,
"compensationMultiplier": 1.0,
"compensationCorrection": 25.0,
"onlyApprovedEntries": true,
"timeCompensationAmount": 10.0
},
"vacationSettings": {
"id": "231b9d9e-fbde-47b7-90da-933758c05bef",
"showVacationAccount": true,
"vacationYearStart": "1970-01-01T00:00:00+00:00",
"workDaysInWeek": 5.0,
"vacationWeeksPerYear": 5.0,
"totalVacationDaysPerYear": 30.0,
"oldVacationDays": 3.0,
"correctionDays": -7.0,
"onlyApprovedDays": true,
"vacationCompensationAmount": null
},
"bankDetails": {
"id": "0d69aa08-7be1-4b5c-8d95-ff201e06bcad",
"paymentType": "bank_transfer",
"nameOfAccountHolder": "John Doe",
"iban": "AT1234567890",
"bicSwift": "BIC",
"bankName": "Bank Name"
}
}
],
"parentGroupRelId": 2545326,
"accountRelId": 2545331,
"historyDataId": "16c18ec8-4dca-47a3-be96-eb888a4aa84c"
}
Responses
Code | Title | Description |
---|---|---|
200 | Success | Returned if request was successful. |
400 | Bad Request | Returned if request was bad. |
401 | Unauthorized | Returned if request was not authorized (eg. due to bad API key). |
404 | Not Found | Returned if request could not be found. |
Response JSON example:
{
"items": [
{
"message": "Success",
"data": {
"id": "123abc45-39c5-436f-a70b-d3a14db753c6",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"mobilePhoneNumber": "+43123123"
}
}
],
"valid": true
}