POST /users

Request parameters (without employments)

ParameterTypeDescription
idstringIf provided existing user will be edited. If not provided a new user will be created.
firstNamestringUsers first name.
lastNamestringUsers last name.
emailstringIf provided an email invite will be sent to user.
validFromdateDate 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
validTodateDate 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
genderstringPossible values:
"male", "female", "none"
mobilePhoneNumberstringIf provided then SMS notifications can be sent via the application.
nationalitystringIf desired, provide "country" from Country List.
birthDatedateIf desired, provide Users birth date in ISO-8601 format, eg. 1990-10-22T00:00:00+00:00
availableLoginMethodsarray [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.
addressobjectIf desired an address can be saved.
idstringIf provided existing address will be edited. If not provided a new address will be created.
streetstringStreet of the address.
citystringCity of the address.
statestringState of the address.
postalCodestringPostal code (zip) of the address.
countrystringIf desired, provide "country" from Country List.
exportIdsobjectIf desired, up to three export id's can be used to match user with third party applications.
exportId1stringIf needed provide an export id.
exportId2stringIf needed provide an export id.
exportId3stringIf needed provide an export id.
hardwareTerminalChipIdstringProvide a chip id of users hardware terminal, if available.
rolesarray [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).
rolestringPossible roles: "employee", "approver", "manager", "administrator", "main_administrator"
organizationsarray [object]Provide "name" or "id" where user will get the role assigned. If you provide both then "name" will be ignored.
name (organizations)stringProvide 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)stringProvide 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

ParameterTypeDescription
userEmploymentsarray [object]If desired an array of user employment objects can be created during same POST call.
idstringIf provided existing user employment will be edited. If not provided a new user employment will be created.
basicData object
employmentStartdateDate 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.
employmentEnddateDate 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.
commentstringComment attached to employment.
employeeIdstringEmployee's ID.
employmentIdintegerEmployee's employment ID.
employmentRelationshipstringPossible 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"
dismissReasonstringPossible 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"
openVacationDaysdoubleEmployee's open vacation days after employment's end.
outstandingHoursdoubleEmployee'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.
idstringID of pay schedule to which users employment will be assigned.
insuranceInformation object
healthInsuranceCountrystringEmployee's health insurance country.
If desired, provide "country" from Country List.
healthInsuranceNumberstringEmployee's health insurance number.
tariffGroupstringEmployee's tariff group.
typeOfHealthInsurancestringPossibile values:
"statutory", "private"
healthInsuranceCompanystringName of health insurance company.
employmentContractobject
positionstringEmployee's position.
employmentTypestringPossibile values:
"full_time", "part_time", "marginally", "daily", "independent_contractor", "apprenticeship", "intern", "parent", "inactive", "part_time_student", "other"
weeklyHoursdoubleEmployee's weekly working hours.
probationPerioddateEmployee's probation period. Provide in ISO-8601 format containing a timezone, eg. 2022-02-15T00:00:00+00:00
periodOfNoticestringEmployee's period of notice.
collectiveAgreementobjectEmployee's collective agreement data, if applicable.
collectiveAgreementIdinteger
collectiveAgreementNamestring
usageGroupstring
publicProfileobjectEmployee's public profile data, if applicable.
officestring
departmentstring
costCenterstring
workPhonestring
hrInformationobjectEmployee's HR information, if applicable.
statusstringPossible values:
"active", "inactive", "dormant"
superVisorUserIdstringUser ID of employee's supervisor.
hrContactUserIdstringUser ID of employee's HR contact person.
payrollInformationobjectEmployee's payroll information, if applicable.
Some country specific data may not be needed in certain countries.
taxIdentificationNumberstring
taxOfficeIdinteger
taxClassintegerPossible values:
"1", "2", "3", "4", "5", "6"
localAuthorityIdinteger
workplaceIdinteger
wageTaxAllowancedouble
maritalStatusstringPossible values:
"single", "married", "single_parent", "widowed"
denominationstring
childBenefitdouble
dependantsintegerPossible values:
"0" for not applicable, "1" for one child, "2" for two children, "3" for three children, "4" for four children
childReliefdouble
severeDisabilitybooleanPossible values:
"true", "false"
disabilitystring
highestGraduationstring
highestOccupationstring
buakbooleanPossible values:
"true", "false"
occasionallyEmployedbooleanPossible values:
"true", "false"
employmentBenefitsbooleanPossible values:
"true", "false"
commuterAllowanceinteger
subwayTaxbooleanPossible values:
"true", "false"
municipalTaxbooleanPossible values:
"true", "false"
overtimeSettingsobject
timeCompensationAmountdoubleEmployee's compensation amount of overtimes which will be added (or subtracted if negative value) to employee's overtime pool.
vacationSettingsobject
vacationCompensationAmountdoubleEmployee's compensation amount of vacation hours which will be added (or subtracted if negative value) to employee's vacation pool.
bankDetailsEmployee's bank information details.
paymentTypestringPossible values: "cash", "credit", "bank_transfer"
nameOfAccountHolderstring
ibanstring
bicSwiftstring
bankNamestring

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

CodeTitleDescription
200 SuccessReturned if request was successful.
400Bad RequestReturned if request was bad.
401UnauthorizedReturned if request was not authorized (eg. due to bad API key).
404Not FoundReturned 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
}