Add Or Edit User

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.
email	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
}

POST /users

Add or Edit User Employments

🚧Warning

🚧
Warning