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.
firstName	string	Users first name.
lastName	string	Users last name.
email	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
}