Add Or Edit Organization

POST /organizations

Request parameters

Parameter	Type	Description
id	string	If provided existing organization will be edited. If not provided a new organization will be created.
validFrom	date	Date from when the organization becomes valid and can be selected at time entries. Provide date in ISO-8601 format with +00:00 time zone, eg. 2022-01-01T00:00:00+00:00
validTo	date	Date to until the organization is valid and until it can be selected at time entries. Dates in past mean that this organization is deactivated. Provide date in ISO-8601 format with +00:00 time zone, eg. 2022-01-01T00:00:00+00:00
name	object	Object containing organizations name and description
organizationName	string	A name is mandatory.
description	string	Provide description if desired.
organizationType	object	Object containing organizations type and parent organization.
type	string	Possible types: "project", "subsidiary", "partner", "client", "supplier", "branch", "other" If not provided then "project" will be created.
parentOrganizationUnitId	string	Provide id of parent organization. If not provided then organization will be assigned direct to company (parent = company) if authenticated user has the coresponding permissions, otherwise 401 error will be returned.
address	object	If desired an address can be saved.
relId	long	Provide this id if existing organization 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.
contactInformation	object	Object containing organizations email and phone number.
organizationEmail	string	If desired an email can be saved.
phoneNumber	string	If desired a phone number can be saved.
assignUsers	array	Array of roles which can be assigned to the organization. Possible roles: "employee", "approver", "administrator"
administrators, approvers, employees	array [object]	Provide an array of roles which should be assigned to the organization.
userId	string	Provide the user id's for every role for those users which should be assigned to this organization.
timeTrackingSettings	object	Object of time tracking settings which should apply for this organization. If no settings are provided then inherited settings from parent organization will be considered. If settings are provided then they will apply to child organizations as well (as long as child organization has no setting by itself).
maxTimeEntryLength	integer	Provide maximum allowed length of time entry in milliseconds. E.g. if it is desired that maximum time entries of 9 hours can be saved for this organization, then provide 32400000 (9h x 60min x 60sec x 1000ms).
allowTimeEntriesFromTime	integer	Provide from time in milliseconds from when time entries will be allowed to be saved. E.g. if it is desired that time entries are allowed only from 9 a.m., then provide 32400000 (9h x 60min x 60sec x 1000ms).
allowTimeEntriesToTime	integer	Provide to time in milliseconds until when time entries will be allowed to be saved. E.g. if it is desired that time entries are allowed only till 9 p.m., then provide 75600000 (21h x 60min x 60sec x 1000ms).
minTimeEntryBreakLength	integer	Provide minimum length of breaks in milliseconds. E.g. if every breake which is saved for this organization should have a minimum break of 30 minutes, then provide 1800000 (0,5h x 60min x 60sec x 1000ms).
maxTimeEntryBreakLength	integer	Provide maximum length of breaks in milliseconds. E.g. if every breake which is saved for this organization should have a maximum break of 60 minutes, then provide 3600000 (1h x 60min x 60sec x 1000ms).
roundingTypeTimeEntryStartTime	string	Provide rounding settings for time entries start time. Possible values: "off", "up", "down", "nearest"
roundingAmountTimeEntryStartTime	integer	Provide rounding amount for time entries start time in minutes. Possible values are: 5, 10, 15, 30, 60
roundingTypeTimeEntryEndTime	string	Provide rounding settings for time entries end time. Possible values: "off", "up", "down", "nearest"
roundingAmountTimeEntryEndTime	integer	Provide rounding amount for time entries end time in minutes. Possible values are: 5, 10, 15, 30, 60
roundingTypeBreakStartTime	string	Provide rounding settings for time entries break start time. Possible values: "off", "up", "down", "nearest"
roundingAmountBreakStartTime	integer	Provide rounding amount for time entries break start time in minutes. Possible values are: 5, 10, 15, 30, 60
roundingTypeBreakEndTime	string	Provide rounding settings for time entries break end time. Possible values: "off", "up", "down", "nearest"
roundingAmountBreakEndTime	integer	Provide rounding amount for time entries break end time in minutes. Possible values are: 5, 10, 15, 30, 60
allowTimeEntriesInPast	boolean	Provide "true" if you want to allow that time entries can be saved for the past, otherwise provide "false".
allowTimeEntriesInFuture	boolean	Provide "true" if you want to allow that time entries can be saved for the future, otherwise provide "false".
onlyClockTimeEntriesAllowed	boolean	Provide "true" if you want to allow only clock time entries for this organization, otherwise provide "false".
automaticTargetTimes	boolean	Provide "true" if you want that target times are saved automatically with every time entry, otherwise provide "false".
ignoreTargetTimes	boolean	Provide "true" if you want that target times are ignored when time entries are saved for this organization, otherwise provide "false".
locationTracking	object	Object containing organizations location tracking settings.
isOn	boolean	Provide "true" if you want that time entries can only be saved within a certain GPS location, otherwise provide "false".
locationRadius	integer	If location tracking "isOn" is true, provide the location radius in meter.
latitude	double	If location tracking "isOn" is true, provide GPS location latitude.
longitude	double	If location tracking "isOn" is true, provide GPS location longitude.
clockingSsId	string	Provide WIFI SSID if you want that time entries are saved automatically when users connect to this WIFI.
clockingMacAddress	string	Provide mac address of WIFI router if you want to restrict that automatic WIFI time entries are only saved if users are connected to a certain router.
exportIds	object	If desired, up to three export id's and a hardware terminal id can be used to match organizations 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 users hardware terminal chip id if user is tracking time via a hardware terminal.

Request parameters

Simple request JSON example
An organization will be created if "organizationName" is provided.

{
	"name": {
		"organizationName": "Organization Name"
	}
}

🚧
Warning
If organization "id" is sent in request, then existing organization 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 an organization, then make sure that already saved data is sent in request again in order to avoid deleting this data.

Full request JSON example:

{
	"id": "987abc78-39c5-436f-a70b-d3a14db753c0",
	"validFrom" :"2022-01-01T00:00:00+00:00", 
    "validTo":"2022-12-31T23:59:59+00:00",
	"name": {
		"organizationName": "Organization Name",
		"description": "Description of organization"
	},
	"organizationType": {
		"type": "project", 
		"parentOrganizationUnitId": "123abc78-39c5-436f-a70b-d3a14db753c6"
	},
	"address": {
        "relId":"123456",
        "id": "321abc78-39c5-436f-a70b-d3a14db753c6",
        "street": "",
        "city": "",
        "state": "",
        "postalCode": "",
        "country": "DE" 
    },
	"contactInformation": {
		"organizationEmail": "[email protected]",
		"phoneNumber":"+49123456789"
	},
	
	"assignUsers": {
		"administrators": [
        {
            "userId": "c4206912-62a6-4ca6-af24-f95d99624615"
        }],
		"approvers": [
        {
            "userId": "91de12c1-4237-431f-a408-e4f7013434b4"
        }],
		"employees": [
        {
            "userId": "993ea1fb-ae4a-422e-9e90-5ecdbb1afb7f"
        }]
	},
	"timeTrackingSettings": {
		"maxTimeEntryLength":"",
		"allowTimeEntriesFromTime": "", 
		"allowTimeEntriesToTime": "",
		"minTimeEntryBreakLength": "",
		"maxTimeEntryBreakLength": "",
		"roundingTypeTimeEntryStartTime": "off", 
		"roundingAmountTimeEntryStartTime": "",
		"roundingTypeTimeEntryEndTime": "off", 
		"roundingAmountTimeEntryEndTime": "",
		"roundingTypeBreakStartTime": "off", 
		"roundingAmountBreakStartTime": "",
		"roundingTypeBreakEndTime": "off", 
		"roundingAmountBreakEndTime":"",
		"allowTimeEntriesInPast": "true",
		"allowTimeEntriesInFuture": "true",
		"onlyClockTimeEntriesAllowed": "false",
		"automaticTargetTimes": "false",
		"ignoreTargetTimes": "true"
	},
	"locationTracking": {
		"isOn": "true",
		"locationRadius": "100",
		"latitude": 123.456,
		"longitude": 987.654,
		"clockingMacAddress": "",
		"clockingSsId": ""
	},
    "exportIds": {
        "exportId1": "123",
        "exportId2": "456",
        "exportId3": "789",
        "hardwareTerminalChipId": "chip 123"
    }
}

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.

📘
Editing organization depending on assigned roles
If an organization has assigned higher roles than the authenticated user, then authenticated user with lower role will not be able to edit this organization.
If an organization has assigned lower or equal roles than the authenticated user, then authenticated user will be able to edit this organization.

Response JSON example:

{
    "items": [
        {
            "message": "Success",
            "data": {
                "id": "123abc45-39c5-436f-a70b-d3a14db753c6"
            }
        }
    ],
    "valid": true
}

Add Or Edit Organization

POST /organizations

🚧
Warning

📘
Editing organization depending on assigned roles

POST /organizations

🚧Warning

📘Editing organization depending on assigned roles

🚧
Warning

📘
Editing organization depending on assigned roles