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. |
firstName | string | Users first name. |
lastName | string | Users last name. |
string | If provided an email invite will be sent to user. | |
validFrom | date | Date from which the user can log in and use the application. Provide date in ISO-8601 format, 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 format, 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 format, eg. 1990-10-22T00:00:00+00:00 |
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. |
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 "name" or "id" where user will get the role assigned. If you provide both then "name" will be ignored. |
name (organizations) | string | Provide name of organization where user will get the role assigned. If two or more organizations have the same name a random of these organizations will be chosen. |
id (organizations) | string | Provide id of organization. Contrary to the name the id of the organization is unique and should be a preferred use compared to the name. |
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 format containing a timezone, 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 format containing a timezone, 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 format containing a timezone, 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 | |
timeCompensationAmount | double | Employee's compensation amount of overtimes which will be added (or subtracted if negative value) to employee's overtime pool. |
vacationSettings | object | |
vacationCompensationAmount | double | Employee's compensation amount of vacation hours which will be added (or subtracted if negative value) to employee's vacation pool. |
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": "123abc45-39c5-436f-a70b-d3a14db753c6",
"firstName": "John",
"lastName": "Doe",
"email": "[email protected]",
"validFrom" :"2022-01-01T00:00:00+00:00",
"validTo":"2022-12-31T23:59:59+00:00",
"gender": "none",
"mobilePhoneNumber": "+43123123",
"nationality": "DE",
"birthDate" : "1985-04-25",
"availableLoginMethods": [
0,
1
],
"address": {
"id": "321abc78-39c5-436f-a70b-d3a14db753c6",
"street": "",
"city": "",
"state": "",
"postalCode": "",
"country": "DE"
},
"exportIds": {
"exportId1": "",
"exportId2": "",
"exportId3": "",
"hardwareTerminalChipId": ""
},
"roles": [
{
"role": "approver",
"organizations": [
{
"name": "Name of organization" OR "id": "123abc45-39c5-436f-a70b-123456789012"
},
{
"name": "Name of organization" OR "id": "321abc45-39c5-436f-a70b-123456789012"
}]
},
{
"role": "employee",
"organizations": [
{
"name": "Name of organization" OR "id": "987abc45-39c5-436f-a70b-123456789012"
},
{
"name": "Name of organization" OR "id": "456abc45-39c5-436f-a70b-123456789012"
}]
}
],
"userEmployments": [
{
"id": "123abc45-39c5-436f-abab-d3a14db753c6",
"basicData": {
"employmentStart": "2022-01-15T00:00:00+00:00",
"employmentEnd": "",
"comment": "Test comment which will be sent to Payroll Accountant",
"employeeId": "123",
"employmentId": "321",
"employmentRelationship": "worker",
"dismissReason": "mutual_notice",
"openVacationDays": "231.1",
"outstandingHours": "123.3"
},
"paySchedules": [
{
"id": "12345678-215a-4023-a759-f125a6202b93"
},
{
"id": "87654321-8849-4b0d-b8ed-1fc1d5fc08aa"
}
],
"insuranceInformation": {
"healthInsuranceCountry": "DE",
"healthInsuranceNumber": "123",
"tariffGroup": "321",
"typeOfHealthInsurance": "private",
"healthInsuranceCompany": "Insurance Corp."
},
"employmentContract": {
"position": "Manager",
"employmentType": "full_time",
"weeklyHours": "35",
"probationPeriod": "2022-02-15T00:00:00+00:00",
"periodOfNotice": "2 Weeks"
},
"collectiveAgreement": {
"collectiveAgreementId": "123",
"collectiveAgreementName": "Workers Agreement",
"usageGroup": "123ABC"
},
"publicProfile": {
"office": "Main Office",
"department": "HR Department",
"costCenter": "987ABC",
"workPhone": "+49123"
},
"hrInformation": {
"status": "active",
"superVisorUserId": "87654321-abcd-4b0d-b8ed-1fc1d5fc08aa",
"hrContactUserId": "87654321-efgh-4b0d-b8ed-1fc1d5fc08aa"
},
"payrollInformation": {
"taxIdentificationNumber": "number",
"taxOfficeId": "1111",
"taxClass": "1",
"localAuthorityId": "222",
"workplaceId": "123",
"wageTaxAllowance": "1.2",
"maritalStatus": "married",
"denomination": "denomination",
"childBenefit": "5.1",
"dependants": "0",
"childRelief": "10.1",
"severeDisability": "true",
"disability": "disability",
"highestGraduation": "graduation",
"highestOccupation": "occupation",
"buak": "false",
"occasionallyEmployed": "false",
"employmentBenefits": "false",
"commuterAllowance": "23",
"subwayTax": "true",
"municipalTax": "false"
},
"overtimeSettings": {
"timeCompensationAmount": "123.32"
},
"vacationSettings": {
"vacationCompensationAmount": "3.12"
},
"bankDetails": {
"paymentType": "bank_transfer",
"nameOfAccountHolder": "John Doe",
"iban": "DE1234567890",
"bicSwift": "XXXYYY",
"bankName": "Bank of America"
}
}
]
}
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
}