Octaved Flow (v1)

Download OpenAPI specification:Download

Documentation for the Octaved Flow API

Anything declared deprecated will be available for at least 6 months. After 6 months, it becomes a breaking change.

You can find the API changelog on the Octaved Flow website.

Please note that for arrays in query parameters, the parameter name must be appended by [] and each array item is added separately.
Example: For ids [123, 456, 789] the query string would look like ?ids[]=123&ids[]=456&ids[]=789

Customers

Routes for customers

Gets customers

Gets all customers if no ids are provided in the query

query Parameters

ids[]

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the customers

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"customerNumber": "string",
"defaultBillingType": null,
"journeyBillingMode": null,
"fileExportLanguage": "de",
"isLocked": false,
"isInternal": false,
"locations": [{"id": "E9996334F8134DBCBE18948284698BB2",
"name": "string",
"number": "string"
}
],
"name": "string",
"requiresInternalCharge": false,
"priceCategoryOverrides": { },
"priceSurchargeOverrides": { },
"showSignatureFieldInPdfTimeSheets": true
}
]

Creates a customer

Request Body schema: application/json
required

customerNumber	string <= 191 characters The customer number.
	null or EnumFlowPidBillingType (string) Default: null The preselected billing type for new work packages in the GUI if this customer is not internal or requires charge.
	null or JourneyBillingMode (string) Default: null Defaults to the respective system setting if `null`.
fileExportLanguage	string (SupportedLanguageSchema) Enum: "de" "en" "es" "fr" "it" "pt" The language used in file exports such as time sheets.
isLocked	boolean Default: false Locked customers cannot be selected for new projects anymore.
isInternal	boolean Default: false Whether or not this is an internal customer.
	Array of CustomerLocationSchema (object) or CustomerLocationSchema (object) (CustomerLocationSchema) The customer locations. Either the id or number has to be given when patching. The array has to be complete when patching, missing locations in the patch are deleted from the database.
name required	string <= 191 characters The name of the customer.
requiresInternalCharge	boolean Default: false If 'isInternal' is true, this flag controls whether or not the customer is charged.
	object Customer specific overrides to the price category settings.
	object Customer specific overrides to the price surcharge settings.
showSignatureFieldInPdfTimeSheets	boolean Defaults to the system setting `fileExports.timeSheets.showSignatureField`.

Responses

Request samples

Payload

Content type

application/json

{"customerNumber": "string",
"defaultBillingType": null,
"journeyBillingMode": null,
"fileExportLanguage": "de",
"isLocked": false,
"isInternal": false,
"locations": [{"id": "E9996334F8134DBCBE18948284698BB2",
"name": "string",
"number": "string"
}
],
"name": "string",
"requiresInternalCharge": false,
"priceCategoryOverrides": { },
"priceSurchargeOverrides": { },
"showSignatureFieldInPdfTimeSheets": true
}

Response samples

201

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Gets one customer

path Parameters

customerId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the customer

Responses

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2",
"customerNumber": "string",
"defaultBillingType": null,
"journeyBillingMode": null,
"fileExportLanguage": "de",
"isLocked": false,
"isInternal": false,
"locations": [{"id": "E9996334F8134DBCBE18948284698BB2",
"name": "string",
"number": "string"
}
],
"name": "string",
"requiresInternalCharge": false,
"priceCategoryOverrides": { },
"priceSurchargeOverrides": { },
"showSignatureFieldInPdfTimeSheets": true
}

Creates a customer

path Parameters

customerId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the customer

Request Body schema: application/json
required

customerNumber	string <= 191 characters The customer number.
	null or EnumFlowPidBillingType (string) Default: null The preselected billing type for new work packages in the GUI if this customer is not internal or requires charge.
	null or JourneyBillingMode (string) Default: null Defaults to the respective system setting if `null`.
fileExportLanguage	string (SupportedLanguageSchema) Enum: "de" "en" "es" "fr" "it" "pt" The language used in file exports such as time sheets.
isLocked	boolean Default: false Locked customers cannot be selected for new projects anymore.
isInternal	boolean Default: false Whether or not this is an internal customer.
	Array of CustomerLocationSchema (object) or CustomerLocationSchema (object) (CustomerLocationSchema) The customer locations. Either the id or number has to be given when patching. The array has to be complete when patching, missing locations in the patch are deleted from the database.
name required	string <= 191 characters The name of the customer.
requiresInternalCharge	boolean Default: false If 'isInternal' is true, this flag controls whether or not the customer is charged.
	object Customer specific overrides to the price category settings.
	object Customer specific overrides to the price surcharge settings.
showSignatureFieldInPdfTimeSheets	boolean Defaults to the system setting `fileExports.timeSheets.showSignatureField`.

Responses

Request samples

Payload

Content type

application/json

{"customerNumber": "string",
"defaultBillingType": null,
"journeyBillingMode": null,
"fileExportLanguage": "de",
"isLocked": false,
"isInternal": false,
"locations": [{"id": "E9996334F8134DBCBE18948284698BB2",
"name": "string",
"number": "string"
}
],
"name": "string",
"requiresInternalCharge": false,
"priceCategoryOverrides": { },
"priceSurchargeOverrides": { },
"showSignatureFieldInPdfTimeSheets": true
}

Patches a customer

path Parameters

customerId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the customer

Request Body schema: application/json
required

customerNumber	string <= 191 characters The customer number.
	null or EnumFlowPidBillingType (string) Default: null The preselected billing type for new work packages in the GUI if this customer is not internal or requires charge.
	null or JourneyBillingMode (string) Default: null Defaults to the respective system setting if `null`.
fileExportLanguage	string (SupportedLanguageSchema) Enum: "de" "en" "es" "fr" "it" "pt" The language used in file exports such as time sheets.
isLocked	boolean Default: false Locked customers cannot be selected for new projects anymore.
isInternal	boolean Default: false Whether or not this is an internal customer.
	Array of CustomerLocationSchema (object) or CustomerLocationSchema (object) (CustomerLocationSchema) The customer locations. Either the id or number has to be given when patching. The array has to be complete when patching, missing locations in the patch are deleted from the database.
name	string <= 191 characters The name of the customer.
requiresInternalCharge	boolean Default: false If 'isInternal' is true, this flag controls whether or not the customer is charged.
	object Customer specific overrides to the price category settings.
	object Customer specific overrides to the price surcharge settings.
showSignatureFieldInPdfTimeSheets	boolean Defaults to the system setting `fileExports.timeSheets.showSignatureField`.

Responses

Request samples

Payload

Content type

application/json

{"customerNumber": "string",
"defaultBillingType": null,
"journeyBillingMode": null,
"fileExportLanguage": "de",
"isLocked": false,
"isInternal": false,
"locations": [{"id": "E9996334F8134DBCBE18948284698BB2",
"name": "string",
"number": "string"
}
],
"name": "string",
"requiresInternalCharge": false,
"priceCategoryOverrides": { },
"priceSurchargeOverrides": { },
"showSignatureFieldInPdfTimeSheets": true
}

Deletes a customer

path Parameters

customerId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the customer

Responses

Simple search

Use one ident/value pair to search for a list of customer ids.
See the request body section for a list of supported search idents.

path Parameters

ident required	string
value	string The content/format depends on the search ident.

Request Body schema: Supported search idents and their values
required

customerNumber	string non-empty
isInternal	string Enum: "0" "1"
isLocked	string Enum: "0" "1"
name	string non-empty
requiresInternalCharge	string Enum: "0" "1" Only finds internal customers

Responses

Response samples

200

Content type

application/json

["E9996334F8134DBCBE18948284698BB2"
]

Complex search

Use "and"-, "or"- or "not"-objects to assemble the desired search query. E.g.:

{"and":[{"ident":"propertyA","value":"foo"},{"or":[{"ident":"isOfSomeKindX"},{"ident":"propertyB","value":"bar"}]},{"not":{"ident":"isOfSomeKindY"}}]}

See the simple search request for the supported search idents.

Request Body schema: application/json
required

One of

ident required	string non-empty
value	string

Responses

Request samples

Payload

Content type

application/json

Example

condition

{"ident": "string",
"value": "string"
}

Response samples

200

Content type

application/json

["E9996334F8134DBCBE18948284698BB2"
]

Labels

Routes to get and manage labels

Get all labels

Get all labels associated with the organization

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"name": "string",
"translations": { },
"color": "7c9754",
"isActive": true,
"projectFolders": ["E9996334F8134DBCBE18948284698BB2"
]
}
]

Create a label

Creates a new label

Request Body schema: application/json
required

name required	string
	null or object
color required	string = 6 characters
isActive	boolean Default: true
projectFolders	Array of strings (uuidArray) [^[0-9A-F]{32}$]

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"translations": { },
"color": "7c9754",
"isActive": true,
"projectFolders": ["E9996334F8134DBCBE18948284698BB2"
]
}

Response samples

201

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Create a label

Creates a new label with the given id

path Parameters

labelId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the label

Request Body schema: application/json
required

name required	string
	null or object
color required	string = 6 characters
isActive	boolean Default: true
projectFolders	Array of strings (uuidArray) [^[0-9A-F]{32}$]

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"translations": { },
"color": "7c9754",
"isActive": true,
"projectFolders": ["E9996334F8134DBCBE18948284698BB2"
]
}

Response samples

201

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Patches a label

path Parameters

labelId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the label

Request Body schema: application/json
required

name	string
	null or object
color	string = 6 characters
isActive	boolean Default: true
projectFolders	Array of strings (uuidArray) [^[0-9A-F]{32}$]

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"translations": { },
"color": "7c9754",
"isActive": true,
"projectFolders": ["E9996334F8134DBCBE18948284698BB2"
]
}

Deletes a label

path Parameters

labelId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the label

Responses

General

General routes for all node types

Gets nodes by ids

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the nodes

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"nodeType": "projectFolder",
"name": "string"
}
]

Gets a node

path Parameters

nodeId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the node

Responses

Response samples

200

Content type

application/json

Example

projectFolder

{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"nodeType": "projectFolder",
"name": "string"
}

Simple search

Use one ident/value pair to search for a list of node ids.
See the request body section for a list of supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

path Parameters

ident required	string
value	string The content/format depends on the search ident.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: Supported search idents and their values
required

ancestorsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all ancestor node ids in order, the direct parent first.
childrenOf	string (uuid) ^[0-9A-F]{32}$ A node id to find the direct child node ids.
descendantsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all descendant node ids (exclusive the given node id).
isArchived	string Value: "" No value used
labelId	string (uuid) ^[0-9A-F]{32}$ The id of the label to look for.
referenceNumber	string (varchar191) <= 191 characters
name	string non-empty
nodeType	string (NodeType) Enum: "boardPost" "group" "materialResource" "materialResourceFolder" "project" "projectFolder" "responsibleNode" "subWorkPackage" "task" "taskSection" "userNode" "workPackage"

Responses

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Complex search

Use "and"-, "or"- or "not"-objects to assemble the desired search query. E.g.:

{"and":[{"ident":"propertyA","value":"foo"},{"or":[{"ident":"isOfSomeKindX"},{"ident":"propertyB","value":"bar"}]},{"not":{"ident":"isOfSomeKindY"}}]}

See the simple search request for the supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: application/json
required

One of

ident required	string non-empty
value	string

Responses

Request samples

Payload

Content type

application/json

Example

condition

{"ident": "string",
"value": "string"
}

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Archive subtree

Archives or unarchives the entire subtree defined by nodeId

path Parameters

nodeId required	string (uuid) ^[0-9A-F]{32}$ Example: E9996334F8134DBCBE18948284698BB2 UUID of a node
archive required	string Enum: "0" "1" Whether to archive or unarchive

Responses

Project folders

Routes for project folders

Gets project folders by ids

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the project folders

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"nodeType": "projectFolder",
"name": "string"
}
]

Creates a project folder

Request Body schema: application/json
required

parentNodeId	string^[0-9A-F]{32}$ Default: "<root project folder id>" The UUID of the parent, which must be another project folder.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
name required	string (varchar191) <= 191 characters

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "<root project folder id>",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"name": "string"
}

Response samples

201

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Gets a project folder

path Parameters

projectFolderId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the project folder

Responses

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"nodeType": "projectFolder",
"name": "string"
}

Creates a project folder

path Parameters

projectFolderId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the project folder

Request Body schema: application/json
required

parentNodeId	string^[0-9A-F]{32}$ Default: "<root project folder id>" The UUID of the parent, which must be another project folder.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
name required	string (varchar191) <= 191 characters

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "<root project folder id>",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"name": "string"
}

Patches a project folder

path Parameters

projectFolderId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the project folder

Request Body schema: application/json
required

color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
name	string (varchar191) <= 191 characters

Responses

Request samples

Payload

Content type

application/json

{"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"name": "string"
}

Deletes a project folder

path Parameters

projectFolderId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the project folder

Responses

Simple search

Use one ident/value pair to search for a list of project folder ids.
See the request body section for a list of supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

path Parameters

ident required	string
value	string The content/format depends on the search ident.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: Supported search idents and their values
required

ancestorsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all ancestor node ids in order, the direct parent first.
childrenOf	string (uuid) ^[0-9A-F]{32}$ A node id to find the direct child node ids.
descendantsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all descendant node ids (exclusive the given node id).
isArchived	string Value: "" No value used
labelId	string (uuid) ^[0-9A-F]{32}$ The id of the label to look for.
referenceNumber	string (varchar191) <= 191 characters
name	string non-empty

Responses

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Complex search

Use "and"-, "or"- or "not"-objects to assemble the desired search query. E.g.:

{"and":[{"ident":"propertyA","value":"foo"},{"or":[{"ident":"isOfSomeKindX"},{"ident":"propertyB","value":"bar"}]},{"not":{"ident":"isOfSomeKindY"}}]}

See the simple search request for the supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: application/json
required

One of

ident required	string non-empty
value	string

Responses

Request samples

Payload

Content type

application/json

Example

condition

{"ident": "string",
"value": "string"
}

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Projects

Routes for projects

Gets projects by ids

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the projects

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"dueDate": "2020-03-23",
"nodeType": "project",
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
},
"minMaxPlanningDateInSubtree": {"minStart": "2020-03-23",
"maxEnd": "2020-03-23"
},
"controlling": {"tasks": {"progress": {"counts": {"completed": 0,
"total": 0
},
"plannedEffortHours": {"completed": 0,
"total": 0
}
}
},
"workPackages": {"progress": {"counts": {"completed": 0,
"total": 0
},
"targetEffortHours": {"completed": 0,
"total": 0
}
}
}
},
"flowCustomer": "E9996334F8134DBCBE18948284698BB2",
"isLocked": false,
"isClosed": false,
"isTemplate": false,
"maxEffort": 125.5,
"enforceMaxEffort": true,
"showMaxEffortInDays": true,
"maxPrice": 125.5
}
]

Creates a project

Request Body schema: application/json
required

parentNodeId	string (uuid) ^[0-9A-F]{32}$ Default: "<root project folder id>" The UUID of the Flow-OU, where this project is to be created.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
description	string <= 5000 characters The description.
name required	string <= 191 characters The name.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
flowCustomer required	string^[0-9A-F]{32}$ The UUID of the customer.
isLocked	boolean Default: false Suspended or locked for time tracking.
isClosed	boolean Default: false Marks this node as closed.
isTemplate	boolean Default: false Marked as template
	decimal8dot2 (number) or null The maximum effort in hours.
enforceMaxEffort	boolean Default: true If TRUE the project's maxEffort cannot be exceeded by time trackings.
showMaxEffortInDays	boolean Default: true If TRUE the project's maxEffort is displayed in days instead of hours.
	decimal8dot2 (number) or null The maximum price.
	(object or object or object) or null (patchNullable)

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"flowCustomer": "E9996334F8134DBCBE18948284698BB2",
"isLocked": false,
"isClosed": false,
"isTemplate": false,
"maxEffort": 125.5,
"enforceMaxEffort": true,
"showMaxEffortInDays": true,
"maxPrice": 125.5,
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
}
}

Response samples

201

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Gets a project

path Parameters

projectId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the project

Responses

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"dueDate": "2020-03-23",
"nodeType": "project",
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
},
"minMaxPlanningDateInSubtree": {"minStart": "2020-03-23",
"maxEnd": "2020-03-23"
},
"controlling": {"tasks": {"progress": {"counts": {"completed": 0,
"total": 0
},
"plannedEffortHours": {"completed": 0,
"total": 0
}
}
},
"workPackages": {"progress": {"counts": {"completed": 0,
"total": 0
},
"targetEffortHours": {"completed": 0,
"total": 0
}
}
}
},
"flowCustomer": "E9996334F8134DBCBE18948284698BB2",
"isLocked": false,
"isClosed": false,
"isTemplate": false,
"maxEffort": 125.5,
"enforceMaxEffort": true,
"showMaxEffortInDays": true,
"maxPrice": 125.5
}

Creates a project

path Parameters

projectId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the project

Request Body schema: application/json
required

parentNodeId	string (uuid) ^[0-9A-F]{32}$ Default: "<root project folder id>" The UUID of the Flow-OU, where this project is to be created.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
description	string <= 5000 characters The description.
name required	string <= 191 characters The name.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
flowCustomer required	string^[0-9A-F]{32}$ The UUID of the customer.
isLocked	boolean Default: false Suspended or locked for time tracking.
isClosed	boolean Default: false Marks this node as closed.
isTemplate	boolean Default: false Marked as template
	decimal8dot2 (number) or null The maximum effort in hours.
enforceMaxEffort	boolean Default: true If TRUE the project's maxEffort cannot be exceeded by time trackings.
showMaxEffortInDays	boolean Default: true If TRUE the project's maxEffort is displayed in days instead of hours.
	decimal8dot2 (number) or null The maximum price.
	(object or object or object) or null (patchNullable)

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"flowCustomer": "E9996334F8134DBCBE18948284698BB2",
"isLocked": false,
"isClosed": false,
"isTemplate": false,
"maxEffort": 125.5,
"enforceMaxEffort": true,
"showMaxEffortInDays": true,
"maxPrice": 125.5,
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
}
}

Patches a project

path Parameters

projectId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the project

Request Body schema: application/json
required

color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
description	string <= 5000 characters The description.
name	string <= 191 characters The name.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
flowCustomer	string^[0-9A-F]{32}$ The UUID of the customer.
isLocked	boolean Default: false Suspended or locked for time tracking.
isClosed	boolean Default: false Marks this node as closed.
isTemplate	boolean Default: false Marked as template
	decimal8dot2 (number) or null The maximum effort in hours.
enforceMaxEffort	boolean Default: true If TRUE the project's maxEffort cannot be exceeded by time trackings.
showMaxEffortInDays	boolean Default: true If TRUE the project's maxEffort is displayed in days instead of hours.
	decimal8dot2 (number) or null The maximum price.
	(object or object or object) or null (patchNullable)

Responses

Request samples

Payload

Content type

application/json

{"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"flowCustomer": "E9996334F8134DBCBE18948284698BB2",
"isLocked": false,
"isClosed": false,
"isTemplate": false,
"maxEffort": 125.5,
"enforceMaxEffort": true,
"showMaxEffortInDays": true,
"maxPrice": 125.5,
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
}
}

Deletes a project

path Parameters

projectId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the project

Responses

Simple search

Use one ident/value pair to search for a list of project ids.
See the request body section for a list of supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

path Parameters

ident required	string
value	string The content/format depends on the search ident.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: Supported search idents and their values
required

ancestorsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all ancestor node ids in order, the direct parent first.
childrenOf	string (uuid) ^[0-9A-F]{32}$ A node id to find the direct child node ids.
descendantsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all descendant node ids (exclusive the given node id).
isArchived	string Value: "" No value used
labelId	string (uuid) ^[0-9A-F]{32}$ The id of the label to look for.
referenceNumber	string (varchar191) <= 191 characters
name	string non-empty
customerId	string (uuid) ^[0-9A-F]{32}$
isTemplate	string Value: "" No value used

Responses

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Complex search

Use "and"-, "or"- or "not"-objects to assemble the desired search query. E.g.:

{"and":[{"ident":"propertyA","value":"foo"},{"or":[{"ident":"isOfSomeKindX"},{"ident":"propertyB","value":"bar"}]},{"not":{"ident":"isOfSomeKindY"}}]}

See the simple search request for the supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: application/json
required

One of

ident required	string non-empty
value	string

Responses

Request samples

Payload

Content type

application/json

Example

condition

{"ident": "string",
"value": "string"
}

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Groups

Routes for groups

Gets groups by ids

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the groups

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"flowCustomer": "E9996334F8134DBCBE18948284698BB2",
"dueDate": "2020-03-23",
"nodeType": "group",
"projectId": "E9996334F8134DBCBE18948284698BB2",
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
},
"minMaxPlanningDateInSubtree": {"minStart": "2020-03-23",
"maxEnd": "2020-03-23"
},
"controlling": {"tasks": {"progress": {"counts": {"completed": 0,
"total": 0
},
"plannedEffortHours": {"completed": 0,
"total": 0
}
}
},
"workPackages": {"progress": {"counts": {"completed": 0,
"total": 0
},
"targetEffortHours": {"completed": 0,
"total": 0
}
}
}
},
"enforceMaxEffort": true,
"groupType": "group",
"isLocked": false,
"isClosed": false,
"maxEffort": 125.5,
"maxPrice": 125.5,
"showMaxEffortInDays": true,
"sortOrder": 0
}
]

Creates a group

Request Body schema: application/json
required

parentNodeId required	string^[0-9A-F]{32}$ The UUID of the parent, which can be a project or a group.
sortedSiblingIds	Array of strings[^[0-9A-F]{32}$] Updates the sort orders of all sibling groups/work pacakges. Should include all sibling ids in order, including the new work package's id.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
description	string <= 5000 characters The description.
name required	string <= 191 characters The name.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
enforceMaxEffort	boolean Default: true If TRUE the group's maxEffort cannot be exceeded by time trackings.
groupType	string Enum: "group" "sprint" "backlog" Type of the group.
isLocked	boolean Default: false Suspended or locked for time tracking.
isClosed	boolean Default: false Marks this node as closed.
	decimal8dot2 (number) or null The maximum effort in hours.
	decimal8dot2 (number) or null The maximum price.
showMaxEffortInDays	boolean Default: true If TRUE the group's maxEffort is displayed in days instead of hours.
sortOrder	integer The zero-based sort order of the entry within its direct parent. If the sort order of two entries is the same, the name determines the order.
	(object or object or object) or null (patchNullable)

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"sortedSiblingIds": ["E9996334F8134DBCBE18948284698BB2"
],
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"enforceMaxEffort": true,
"groupType": "group",
"isLocked": false,
"isClosed": false,
"maxEffort": 125.5,
"maxPrice": 125.5,
"showMaxEffortInDays": true,
"sortOrder": 0,
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
}
}

Response samples

201

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Gets a group

path Parameters

groupId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the group

Responses

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"flowCustomer": "E9996334F8134DBCBE18948284698BB2",
"dueDate": "2020-03-23",
"nodeType": "group",
"projectId": "E9996334F8134DBCBE18948284698BB2",
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
},
"minMaxPlanningDateInSubtree": {"minStart": "2020-03-23",
"maxEnd": "2020-03-23"
},
"controlling": {"tasks": {"progress": {"counts": {"completed": 0,
"total": 0
},
"plannedEffortHours": {"completed": 0,
"total": 0
}
}
},
"workPackages": {"progress": {"counts": {"completed": 0,
"total": 0
},
"targetEffortHours": {"completed": 0,
"total": 0
}
}
}
},
"enforceMaxEffort": true,
"groupType": "group",
"isLocked": false,
"isClosed": false,
"maxEffort": 125.5,
"maxPrice": 125.5,
"showMaxEffortInDays": true,
"sortOrder": 0
}

Creates a group

path Parameters

groupId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the group

Request Body schema: application/json
required

parentNodeId required	string^[0-9A-F]{32}$ The UUID of the parent, which can be a project or a group.
sortedSiblingIds	Array of strings[^[0-9A-F]{32}$] Updates the sort orders of all sibling groups/work pacakges. Should include all sibling ids in order, including the new work package's id.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
description	string <= 5000 characters The description.
name required	string <= 191 characters The name.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
enforceMaxEffort	boolean Default: true If TRUE the group's maxEffort cannot be exceeded by time trackings.
groupType	string Enum: "group" "sprint" "backlog" Type of the group.
isLocked	boolean Default: false Suspended or locked for time tracking.
isClosed	boolean Default: false Marks this node as closed.
	decimal8dot2 (number) or null The maximum effort in hours.
	decimal8dot2 (number) or null The maximum price.
showMaxEffortInDays	boolean Default: true If TRUE the group's maxEffort is displayed in days instead of hours.
sortOrder	integer The zero-based sort order of the entry within its direct parent. If the sort order of two entries is the same, the name determines the order.
	(object or object or object) or null (patchNullable)

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"sortedSiblingIds": ["E9996334F8134DBCBE18948284698BB2"
],
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"enforceMaxEffort": true,
"groupType": "group",
"isLocked": false,
"isClosed": false,
"maxEffort": 125.5,
"maxPrice": 125.5,
"showMaxEffortInDays": true,
"sortOrder": 0,
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
}
}

Patches a group

path Parameters

groupId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the group

Request Body schema: application/json
required

color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
description	string <= 5000 characters The description.
name	string <= 191 characters The name.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
enforceMaxEffort	boolean Default: true If TRUE the group's maxEffort cannot be exceeded by time trackings.
groupType	string Enum: "group" "sprint" "backlog" Type of the group.
isLocked	boolean Default: false Suspended or locked for time tracking.
isClosed	boolean Default: false Marks this node as closed.
	decimal8dot2 (number) or null The maximum effort in hours.
	decimal8dot2 (number) or null The maximum price.
showMaxEffortInDays	boolean Default: true If TRUE the group's maxEffort is displayed in days instead of hours.
sortOrder	integer The zero-based sort order of the entry within its direct parent. If the sort order of two entries is the same, the name determines the order.
	(object or object or object) or null (patchNullable)

Responses

Request samples

Payload

Content type

application/json

{"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"enforceMaxEffort": true,
"groupType": "group",
"isLocked": false,
"isClosed": false,
"maxEffort": 125.5,
"maxPrice": 125.5,
"showMaxEffortInDays": true,
"sortOrder": 0,
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
}
}

Deletes a group

path Parameters

groupId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the group

Responses

Simple search

Use one ident/value pair to search for a list of group ids.
See the request body section for a list of supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

path Parameters

ident required	string
value	string The content/format depends on the search ident.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: Supported search idents and their values
required

ancestorsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all ancestor node ids in order, the direct parent first.
childrenOf	string (uuid) ^[0-9A-F]{32}$ A node id to find the direct child node ids.
descendantsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all descendant node ids (exclusive the given node id).
isArchived	string Value: "" No value used
labelId	string (uuid) ^[0-9A-F]{32}$ The id of the label to look for.
referenceNumber	string (varchar191) <= 191 characters
name	string non-empty
customerId	string (uuid) ^[0-9A-F]{32}$

Responses

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Complex search

Use "and"-, "or"- or "not"-objects to assemble the desired search query. E.g.:

{"and":[{"ident":"propertyA","value":"foo"},{"or":[{"ident":"isOfSomeKindX"},{"ident":"propertyB","value":"bar"}]},{"not":{"ident":"isOfSomeKindY"}}]}

See the simple search request for the supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: application/json
required

One of

ident required	string non-empty
value	string

Responses

Request samples

Payload

Content type

application/json

Example

condition

{"ident": "string",
"value": "string"
}

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Work packages

Routes for work packages

Gets work packages by ids

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the work packages

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"completedBy": "E9996334F8134DBCBE18948284698BB2",
"completedOn": 1580555700,
"flowCustomer": "E9996334F8134DBCBE18948284698BB2",
"nodeType": "workPackage",
"planningDates": ["E9996334F8134DBCBE18948284698BB2"
],
"projectId": "E9996334F8134DBCBE18948284698BB2",
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
},
"billingType": "effort",
"effortFrom": 125.5,
"effortTo": 125.5,
"fixedPrice": 125.5,
"freeOfChargeReason": "service",
"isCompleted": false,
"isApprovedForBilling": false,
"isLocked": false,
"isClosed": false,
"isOffer": false,
"maxEffort": 125.5,
"priceCategory": "E9996334F8134DBCBE18948284698BB2",
"sortOrder": 0,
"timeTrackingReferenceNodeType": "any",
"usePriceCategoryPerTimeTracking": false
}
]

Creates a work package

Request Body schema: application/json
required

parentNodeId required	string^[0-9A-F]{32}$ The UUID of the parent, which can be a project or a group.
sortedSiblingIds	Array of strings[^[0-9A-F]{32}$] Updates the sort orders of all sibling groups/work pacakges. Should include all sibling ids in order, including the new work package's id.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
description	string <= 5000 characters The description.
name required	string <= 191 characters The name.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
billingType	string Default: "effort" Enum: "contingent" "effort" "effortCap" "effortEst" "effortFromTo" "freeOfCharge" "fixedPrice" The billing type. All `effort*` types are hourly billable.
	decimal8dot2 (number) or null The lower limit of effort in hours - used for the 'effortFromTo' billing type.
	decimal8dot2 (number) or null The upper limit of effort in hours - used for the 'effortFromTo' billing type.
	decimal8dot2 (number) or null The price for when the billing type is set to 'fixedPrice'.
freeOfChargeReason	string Default: "service" Enum: "service" "aquisition" "warranty" The reason for when the billing type is 'freeOfCharge'.
isCompleted	boolean Default: false Marks this work package as complete (done).
isApprovedForBilling	boolean Default: false Approved for billing. This flag alone does not lock for time tracking!
isLocked	boolean Default: false Suspended or locked for time tracking.
isClosed	boolean Default: false Marks this node as closed.
isOffer	boolean Default: false
	decimal8dot2 (number) or null The maximum effort in hours - used for all billing types with one limit.
	uuid (string) or null The UUID of the price category.
sortOrder	integer The zero-based sort order of the entry within its direct parent. If the sort order of two entries is the same, the name determines the order.
timeTrackingReferenceNodeType	string Default: "any" Enum: "any" "subWorkPackages" "workPackages" Whether time tracking should be allowed on only work packages or only sub work packages.
usePriceCategoryPerTimeTracking	boolean Default: false If true, all time tracking records are required to provide a price category. When switching to TRUE, all records receive the price category, which the work package currently has. When switching to FALSE, all records lose their price category. Only allowed for hourly billable billing types.
	(object or object or object) or null (patchNullable)

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"sortedSiblingIds": ["E9996334F8134DBCBE18948284698BB2"
],
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"billingType": "effort",
"effortFrom": 125.5,
"effortTo": 125.5,
"fixedPrice": 125.5,
"freeOfChargeReason": "service",
"isCompleted": false,
"isApprovedForBilling": false,
"isLocked": false,
"isClosed": false,
"isOffer": false,
"maxEffort": 125.5,
"priceCategory": "E9996334F8134DBCBE18948284698BB2",
"sortOrder": 0,
"timeTrackingReferenceNodeType": "any",
"usePriceCategoryPerTimeTracking": false,
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
}
}

Response samples

201

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Gets a work package

path Parameters

workPackageId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the work package

Responses

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"completedBy": "E9996334F8134DBCBE18948284698BB2",
"completedOn": 1580555700,
"flowCustomer": "E9996334F8134DBCBE18948284698BB2",
"nodeType": "workPackage",
"planningDates": ["E9996334F8134DBCBE18948284698BB2"
],
"projectId": "E9996334F8134DBCBE18948284698BB2",
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
},
"billingType": "effort",
"effortFrom": 125.5,
"effortTo": 125.5,
"fixedPrice": 125.5,
"freeOfChargeReason": "service",
"isCompleted": false,
"isApprovedForBilling": false,
"isLocked": false,
"isClosed": false,
"isOffer": false,
"maxEffort": 125.5,
"priceCategory": "E9996334F8134DBCBE18948284698BB2",
"sortOrder": 0,
"timeTrackingReferenceNodeType": "any",
"usePriceCategoryPerTimeTracking": false
}

Creates a work package

path Parameters

workPackageId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the work package

Request Body schema: application/json
required

parentNodeId required	string^[0-9A-F]{32}$ The UUID of the parent, which can be a project or a group.
sortedSiblingIds	Array of strings[^[0-9A-F]{32}$] Updates the sort orders of all sibling groups/work pacakges. Should include all sibling ids in order, including the new work package's id.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
description	string <= 5000 characters The description.
name required	string <= 191 characters The name.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
billingType	string Default: "effort" Enum: "contingent" "effort" "effortCap" "effortEst" "effortFromTo" "freeOfCharge" "fixedPrice" The billing type. All `effort*` types are hourly billable.
	decimal8dot2 (number) or null The lower limit of effort in hours - used for the 'effortFromTo' billing type.
	decimal8dot2 (number) or null The upper limit of effort in hours - used for the 'effortFromTo' billing type.
	decimal8dot2 (number) or null The price for when the billing type is set to 'fixedPrice'.
freeOfChargeReason	string Default: "service" Enum: "service" "aquisition" "warranty" The reason for when the billing type is 'freeOfCharge'.
isCompleted	boolean Default: false Marks this work package as complete (done).
isApprovedForBilling	boolean Default: false Approved for billing. This flag alone does not lock for time tracking!
isLocked	boolean Default: false Suspended or locked for time tracking.
isClosed	boolean Default: false Marks this node as closed.
isOffer	boolean Default: false
	decimal8dot2 (number) or null The maximum effort in hours - used for all billing types with one limit.
	uuid (string) or null The UUID of the price category.
sortOrder	integer The zero-based sort order of the entry within its direct parent. If the sort order of two entries is the same, the name determines the order.
timeTrackingReferenceNodeType	string Default: "any" Enum: "any" "subWorkPackages" "workPackages" Whether time tracking should be allowed on only work packages or only sub work packages.
usePriceCategoryPerTimeTracking	boolean Default: false If true, all time tracking records are required to provide a price category. When switching to TRUE, all records receive the price category, which the work package currently has. When switching to FALSE, all records lose their price category. Only allowed for hourly billable billing types.
	(object or object or object) or null (patchNullable)

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"sortedSiblingIds": ["E9996334F8134DBCBE18948284698BB2"
],
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"billingType": "effort",
"effortFrom": 125.5,
"effortTo": 125.5,
"fixedPrice": 125.5,
"freeOfChargeReason": "service",
"isCompleted": false,
"isApprovedForBilling": false,
"isLocked": false,
"isClosed": false,
"isOffer": false,
"maxEffort": 125.5,
"priceCategory": "E9996334F8134DBCBE18948284698BB2",
"sortOrder": 0,
"timeTrackingReferenceNodeType": "any",
"usePriceCategoryPerTimeTracking": false,
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
}
}

Patches a work package

path Parameters

workPackageId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the work package

Request Body schema: application/json
required

color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
description	string <= 5000 characters The description.
name	string <= 191 characters The name.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
billingType	string Default: "effort" Enum: "contingent" "effort" "effortCap" "effortEst" "effortFromTo" "freeOfCharge" "fixedPrice" The billing type. All `effort*` types are hourly billable.
	decimal8dot2 (number) or null The lower limit of effort in hours - used for the 'effortFromTo' billing type.
	decimal8dot2 (number) or null The upper limit of effort in hours - used for the 'effortFromTo' billing type.
	decimal8dot2 (number) or null The price for when the billing type is set to 'fixedPrice'.
freeOfChargeReason	string Default: "service" Enum: "service" "aquisition" "warranty" The reason for when the billing type is 'freeOfCharge'.
isCompleted	boolean Default: false Marks this work package as complete (done).
isApprovedForBilling	boolean Default: false Approved for billing. This flag alone does not lock for time tracking!
isLocked	boolean Default: false Suspended or locked for time tracking.
isClosed	boolean Default: false Marks this node as closed.
isOffer	boolean Default: false
	decimal8dot2 (number) or null The maximum effort in hours - used for all billing types with one limit.
	uuid (string) or null The UUID of the price category.
sortOrder	integer The zero-based sort order of the entry within its direct parent. If the sort order of two entries is the same, the name determines the order.
timeTrackingReferenceNodeType	string Default: "any" Enum: "any" "subWorkPackages" "workPackages" Whether time tracking should be allowed on only work packages or only sub work packages.
usePriceCategoryPerTimeTracking	boolean Default: false If true, all time tracking records are required to provide a price category. When switching to TRUE, all records receive the price category, which the work package currently has. When switching to FALSE, all records lose their price category. Only allowed for hourly billable billing types.
	(object or object or object) or null (patchNullable)

Responses

Request samples

Payload

Content type

application/json

{"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"description": "string",
"name": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"billingType": "effort",
"effortFrom": 125.5,
"effortTo": 125.5,
"fixedPrice": 125.5,
"freeOfChargeReason": "service",
"isCompleted": false,
"isApprovedForBilling": false,
"isLocked": false,
"isClosed": false,
"isOffer": false,
"maxEffort": 125.5,
"priceCategory": "E9996334F8134DBCBE18948284698BB2",
"sortOrder": 0,
"timeTrackingReferenceNodeType": "any",
"usePriceCategoryPerTimeTracking": false,
"timeControl": {"mode": "monthly",
"from": "2020-03-23",
"to": null,
"showAfterName": true
}
}

Deletes a work package

path Parameters

workPackageId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the work package

Responses

Simple search

Use one ident/value pair to search for a list of work package ids.
See the request body section for a list of supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

path Parameters

ident required	string
value	string The content/format depends on the search ident.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: Supported search idents and their values
required

ancestorsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all ancestor node ids in order, the direct parent first.
childrenOf	string (uuid) ^[0-9A-F]{32}$ A node id to find the direct child node ids.
descendantsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all descendant node ids (exclusive the given node id).
isArchived	string Value: "" No value used
labelId	string (uuid) ^[0-9A-F]{32}$ The id of the label to look for.
referenceNumber	string (varchar191) <= 191 characters
name	string non-empty
customerId	string (uuid) ^[0-9A-F]{32}$
isApprovedForBilling	string Value: "" No value used
isCompleted	string Value: "" No value used
isLocked	string Value: "" No value used. This state is called 'suspended' in the UI.
isOffer	string Value: "" No value used

Responses

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Complex search

Use "and"-, "or"- or "not"-objects to assemble the desired search query. E.g.:

{"and":[{"ident":"propertyA","value":"foo"},{"or":[{"ident":"isOfSomeKindX"},{"ident":"propertyB","value":"bar"}]},{"not":{"ident":"isOfSomeKindY"}}]}

See the simple search request for the supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: application/json
required

One of

ident required	string non-empty
value	string

Responses

Request samples

Payload

Content type

application/json

Example

condition

{"ident": "string",
"value": "string"
}

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Responsible nodes

EXPERIMENTAL

Sub work packages

Routes for sub work packages

Gets sub work packages by ids

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the sub work packages

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"completedBy": "E9996334F8134DBCBE18948284698BB2",
"completedOn": 1580555700,
"nodeType": "subWorkPackage",
"planningDates": ["E9996334F8134DBCBE18948284698BB2"
],
"projectId": "E9996334F8134DBCBE18948284698BB2",
"name": "string",
"description": "string",
"isCompleted": false,
"isLocked": false,
"maxEffort": 125.5,
"defaultPriceCategory": "E9996334F8134DBCBE18948284698BB2",
"sortOrder": 0
}
]

Creates a sub work package

Request Body schema: application/json
required

parentNodeId required	string^[0-9A-F]{32}$ The UUID of the parent, which must be a work package.
sortedSiblingIds	Array of strings[^[0-9A-F]{32}$] Updates the sort orders of all sibling sub work pacakges. Should include all sibling ids in order, including the new sub work package's id.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
name required	string <= 191 characters The name.
description	string <= 5000 characters The description.
isCompleted	boolean Default: false Marks this sub work package as complete (done).
isLocked	boolean Default: false Suspended or locked for time tracking.
	decimal8dot2 (number) or null The maximum effort in hours
	uuid (string) or null The UUID of the price category that is pre-selected when tracking time. Only used if the parent work package is set to `usePriceCategoryPerTimeTracking=true`.
sortOrder	integer The zero-based sort order of the entry within its direct parent.

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"sortedSiblingIds": ["E9996334F8134DBCBE18948284698BB2"
],
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"name": "string",
"description": "string",
"isCompleted": false,
"isLocked": false,
"maxEffort": 125.5,
"defaultPriceCategory": "E9996334F8134DBCBE18948284698BB2",
"sortOrder": 0
}

Response samples

201

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Gets a sub work package

path Parameters

subWorkPackageId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the sub work package

Responses

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"completedBy": "E9996334F8134DBCBE18948284698BB2",
"completedOn": 1580555700,
"nodeType": "subWorkPackage",
"planningDates": ["E9996334F8134DBCBE18948284698BB2"
],
"projectId": "E9996334F8134DBCBE18948284698BB2",
"name": "string",
"description": "string",
"isCompleted": false,
"isLocked": false,
"maxEffort": 125.5,
"defaultPriceCategory": "E9996334F8134DBCBE18948284698BB2",
"sortOrder": 0
}

Creates a sub work package

path Parameters

subWorkPackageId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the sub work package

Request Body schema: application/json
required

parentNodeId required	string^[0-9A-F]{32}$ The UUID of the parent, which must be a work package.
sortedSiblingIds	Array of strings[^[0-9A-F]{32}$] Updates the sort orders of all sibling sub work pacakges. Should include all sibling ids in order, including the new sub work package's id.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
name required	string <= 191 characters The name.
description	string <= 5000 characters The description.
isCompleted	boolean Default: false Marks this sub work package as complete (done).
isLocked	boolean Default: false Suspended or locked for time tracking.
	decimal8dot2 (number) or null The maximum effort in hours
	uuid (string) or null The UUID of the price category that is pre-selected when tracking time. Only used if the parent work package is set to `usePriceCategoryPerTimeTracking=true`.
sortOrder	integer The zero-based sort order of the entry within its direct parent.

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"sortedSiblingIds": ["E9996334F8134DBCBE18948284698BB2"
],
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"name": "string",
"description": "string",
"isCompleted": false,
"isLocked": false,
"maxEffort": 125.5,
"defaultPriceCategory": "E9996334F8134DBCBE18948284698BB2",
"sortOrder": 0
}

Patches a sub work package

path Parameters

subWorkPackageId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the sub work package

Request Body schema: application/json
required

color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
name	string <= 191 characters The name.
description	string <= 5000 characters The description.
isCompleted	boolean Default: false Marks this sub work package as complete (done).
isLocked	boolean Default: false Suspended or locked for time tracking.
	decimal8dot2 (number) or null The maximum effort in hours
	uuid (string) or null The UUID of the price category that is pre-selected when tracking time. Only used if the parent work package is set to `usePriceCategoryPerTimeTracking=true`.
sortOrder	integer The zero-based sort order of the entry within its direct parent.

Responses

Request samples

Payload

Content type

application/json

{"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"name": "string",
"description": "string",
"isCompleted": false,
"isLocked": false,
"maxEffort": 125.5,
"defaultPriceCategory": "E9996334F8134DBCBE18948284698BB2",
"sortOrder": 0
}

Deletes a sub work package

path Parameters

subWorkPackageId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the sub work package

Responses

Simple search

Use one ident/value pair to search for a list of sub work package ids.
See the request body section for a list of supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

path Parameters

ident required	string
value	string The content/format depends on the search ident.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: Supported search idents and their values
required

ancestorsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all ancestor node ids in order, the direct parent first.
childrenOf	string (uuid) ^[0-9A-F]{32}$ A node id to find the direct child node ids.
descendantsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all descendant node ids (exclusive the given node id).
isArchived	string Value: "" No value used
labelId	string (uuid) ^[0-9A-F]{32}$ The id of the label to look for.
referenceNumber	string (varchar191) <= 191 characters
name	string non-empty

Responses

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Complex search

Use "and"-, "or"- or "not"-objects to assemble the desired search query. E.g.:

{"and":[{"ident":"propertyA","value":"foo"},{"or":[{"ident":"isOfSomeKindX"},{"ident":"propertyB","value":"bar"}]},{"not":{"ident":"isOfSomeKindY"}}]}

See the simple search request for the supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: application/json
required

One of

ident required	string non-empty
value	string

Responses

Request samples

Payload

Content type

application/json

Example

condition

{"ident": "string",
"value": "string"
}

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

TaskSections

Gets task sections by ids

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the taskSections

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"nodeType": "taskSection",
"projectId": "E9996334F8134DBCBE18948284698BB2",
"name": "string",
"sortOrder": 0
}
]

Creates a task section

Request Body schema: application/json
required

parentNodeId required	string^[0-9A-F]{32}$ The UUID of the parent
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
name required	string (varchar191) <= 191 characters
sortOrder	integer Default: 0 The zero-based sort order of the task within its direct parent.

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"name": "string",
"sortOrder": 0
}

Response samples

201

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Gets a task section

path Parameters

taskSectionId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the task section

Responses

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"nodeType": "taskSection",
"projectId": "E9996334F8134DBCBE18948284698BB2",
"name": "string",
"sortOrder": 0
}

Creates a task section

path Parameters

taskSectionId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the task section

Request Body schema: application/json
required

parentNodeId required	string^[0-9A-F]{32}$ The UUID of the parent
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
name required	string (varchar191) <= 191 characters
sortOrder	integer Default: 0 The zero-based sort order of the task within its direct parent.

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"name": "string",
"sortOrder": 0
}

Patches a task section

path Parameters

taskSectionId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the task section

Request Body schema: application/json
required

color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
name	string (varchar191) <= 191 characters
sortOrder	integer Default: 0 The zero-based sort order of the task within its direct parent.

Responses

Request samples

Payload

Content type

application/json

{"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"name": "string",
"sortOrder": 0
}

Deletes a task section

path Parameters

taskSectionId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the task section

Responses

Simple search

Use one ident/value pair to search for a list of task section ids.
See the request body section for a list of supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

path Parameters

ident required	string
value	string The content/format depends on the search ident.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: Supported search idents and their values
required

ancestorsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all ancestor node ids in order, the direct parent first.
childrenOf	string (uuid) ^[0-9A-F]{32}$ A node id to find the direct child node ids.
descendantsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all descendant node ids (exclusive the given node id).
isArchived	string Value: "" No value used
labelId	string (uuid) ^[0-9A-F]{32}$ The id of the label to look for.
referenceNumber	string (varchar191) <= 191 characters

Responses

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Complex search

Use "and"-, "or"- or "not"-objects to assemble the desired search query. E.g.:

{"and":[{"ident":"propertyA","value":"foo"},{"or":[{"ident":"isOfSomeKindX"},{"ident":"propertyB","value":"bar"}]},{"not":{"ident":"isOfSomeKindY"}}]}

See the simple search request for the supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: application/json
required

One of

ident required	string non-empty
value	string

Responses

Request samples

Payload

Content type

application/json

Example

condition

{"ident": "string",
"value": "string"
}

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Tasks

Routes for tasks

Gets tasks by ids

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the tasks

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"completedBy": "E9996334F8134DBCBE18948284698BB2",
"completedOn": 1580555700,
"nodeType": "task",
"planningDates": ["E9996334F8134DBCBE18948284698BB2"
],
"projectId": "E9996334F8134DBCBE18948284698BB2",
"description": "string",
"isCompleted": false,
"name": "string",
"plannedTime": 125.5,
"sortOrder": 0,
"status": "open"
}
]

Creates a task

Request Body schema: application/json
required

parentNodeId required	string^[0-9A-F]{32}$ The UUID of the parent, which can be a work package or another task.
sortedSiblingIds	Array of strings[^[0-9A-F]{32}$] Updates the sort orders of all sibling tasks. Should include all sibling ids in order, including the new task's id.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
description	string <= 5000 characters The description of the task.
isCompleted	boolean Default: false Whehter or not this task is completed (done).
name required	string (varchar191) <= 191 characters
	number or null (decimal8dot2Nullable)
sortOrder	integer Default: 0 The zero-based sort order of the task within its direct parent.
status	string (EnumFlowTaskStatus) Deprecated Default: "open" Enum: "open" "complete" DEPRECATED - use `isCompleted` instead.

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"sortedSiblingIds": ["E9996334F8134DBCBE18948284698BB2"
],
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"description": "string",
"isCompleted": false,
"name": "string",
"plannedTime": 125.5,
"sortOrder": 0,
"status": "open"
}

Response samples

201

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Gets a task

path Parameters

taskId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the task

Responses

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"completedBy": "E9996334F8134DBCBE18948284698BB2",
"completedOn": 1580555700,
"nodeType": "task",
"planningDates": ["E9996334F8134DBCBE18948284698BB2"
],
"projectId": "E9996334F8134DBCBE18948284698BB2",
"description": "string",
"isCompleted": false,
"name": "string",
"plannedTime": 125.5,
"sortOrder": 0,
"status": "open"
}

Creates a task

path Parameters

taskId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the task

Request Body schema: application/json
required

parentNodeId required	string^[0-9A-F]{32}$ The UUID of the parent, which can be a work package or another task.
sortedSiblingIds	Array of strings[^[0-9A-F]{32}$] Updates the sort orders of all sibling tasks. Should include all sibling ids in order, including the new task's id.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
description	string <= 5000 characters The description of the task.
isCompleted	boolean Default: false Whehter or not this task is completed (done).
name required	string (varchar191) <= 191 characters
	number or null (decimal8dot2Nullable)
sortOrder	integer Default: 0 The zero-based sort order of the task within its direct parent.
status	string (EnumFlowTaskStatus) Deprecated Default: "open" Enum: "open" "complete" DEPRECATED - use `isCompleted` instead.

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"sortedSiblingIds": ["E9996334F8134DBCBE18948284698BB2"
],
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"description": "string",
"isCompleted": false,
"name": "string",
"plannedTime": 125.5,
"sortOrder": 0,
"status": "open"
}

Patches a task

path Parameters

taskId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the task

Request Body schema: application/json
required

color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
definesOwnResponsible	boolean Whether this node has own reponsible users/groups or inherits them from its parent node. If this property is set to `false`, `responsibleGroups` and `responsibleUsers` are ignored. If this property is not set while `responsibleGroups` or `responsibleUsers` is set, it defaults to `true`.
responsibleGroups	Array of strings[^[0-9A-F]{32}$] The user group ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleUsers` is set, it defaults to an empty array! Best always set all three property together.
responsibleUsers	Array of strings[^[0-9A-F]{32}$] The user ids responsible for this node. Contains a copy of the parent node if this node is set to `definesOwnResponsible = false`. If this property is not set while `definesOwnResponsible` or `responsibleGroups` is set, it defaults to an empty array! Best always set all three property together.
description	string <= 5000 characters The description of the task.
isCompleted	boolean Default: false Whehter or not this task is completed (done).
name	string (varchar191) <= 191 characters
	number or null (decimal8dot2Nullable)
sortOrder	integer Default: 0 The zero-based sort order of the task within its direct parent.
status	string (EnumFlowTaskStatus) Deprecated Default: "open" Enum: "open" "complete" DEPRECATED - use `isCompleted` instead.

Responses

Request samples

Payload

Content type

application/json

{"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"definesOwnResponsible": true,
"responsibleGroups": [ ],
"responsibleUsers": [ ],
"description": "string",
"isCompleted": false,
"name": "string",
"plannedTime": 125.5,
"sortOrder": 0,
"status": "open"
}

Deletes a task

path Parameters

taskId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the task

Responses

Simple search

Use one ident/value pair to search for a list of task ids.
See the request body section for a list of supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

path Parameters

ident required	string
value	string The content/format depends on the search ident.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: Supported search idents and their values
required

ancestorsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all ancestor node ids in order, the direct parent first.
childrenOf	string (uuid) ^[0-9A-F]{32}$ A node id to find the direct child node ids.
descendantsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all descendant node ids (exclusive the given node id).
isArchived	string Value: "" No value used
labelId	string (uuid) ^[0-9A-F]{32}$ The id of the label to look for.
referenceNumber	string (varchar191) <= 191 characters
isCompleted	string Value: "" No value used
name	string non-empty
status	string (EnumFlowTaskStatus) Deprecated Enum: "open" "complete" DEPRECATED - use `isCompleted` instead

Responses

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Complex search

Use "and"-, "or"- or "not"-objects to assemble the desired search query. E.g.:

{"and":[{"ident":"propertyA","value":"foo"},{"or":[{"ident":"isOfSomeKindX"},{"ident":"propertyB","value":"bar"}]},{"not":{"ident":"isOfSomeKindY"}}]}

See the simple search request for the supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: application/json
required

One of

ident required	string non-empty
value	string

Responses

Request samples

Payload

Content type

application/json

Example

condition

{"ident": "string",
"value": "string"
}

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Responsible users

Get responsible users for multiple nodes

All inheritance and user group memberships are resolved to yield all users finally assigned/responsible for a node. The response is a record of all requested node ids mapping to their respective users.

query Parameters

ids[] required	Array of strings (uuidArray) [^[0-9A-F]{32}$] Example: ids[]=E9996334F8134DBCBE18948284698BB2 UUIDs of the nodes
responsible	string Value: "1" Whether to include responsible users in the result. Defaults to `1` if no filter parameters are present.
projectManager	string Value: "1" Whether to include users in the result who were assigned a project manager role.
anyProjectRole	string Value: "1" Whether to include users in the result who were assigned any project role. Defaults to `1` if no filter parameters are present.
roleId	string (uuid) ^[0-9A-F]{32}$ Example: roleId=E9996334F8134DBCBE18948284698BB2 The UUID of a specific project role to filter for.

Responses

Response samples

200

Content type

application/json

{ }

Planning dates

Routes for planning dates

Get planning dates by their node ids

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the nodes

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"nodeId": "E9996334F8134DBCBE18948284698BB2",
"plannedStart": "2020-03-23 23:59:59",
"plannedEnd": "2020-03-23 23:59:59"
}
]

Time tracking records

Routes for time tracking records

Get time tracking records by ids

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the time tracking records

Responses

Response samples

200

Content type

application/json

[{"billedOn": 1586003400,
"id": "E9996334F8134DBCBE18948284698BB2",
"user": "E9996334F8134DBCBE18948284698BB2",
"workTimeStart": 1586004000,
"workTimeEnd": 1586005800,
"billingStart": 1586003400,
"billingEnd": 1586006100,
"message": "Briefing about Octaved Flow",
"isJourney": false,
"referenceNode": "E9996334F8134DBCBE18948284698BB2",
"workPackage": "E9996334F8134DBCBE18948284698BB2",
"priceCategory": "E9996334F8134DBCBE18948284698BB2",
"priceSurcharge": "E9996334F8134DBCBE18948284698BB2",
"labels": ["E9996334F8134DBCBE18948284698BB2"
]
}
]

Post time tracking record

Request Body schema: application/json
required

	unix (integer) or null The timestamp of the work start time in seconds since 1970-01-01 in the user's timezone. Meaning if the record start is supposed to be 2020-04-04 14:40 in New York, then the unix timestamp for 2020-04-04 14:40 UTC shall be sent.
	unix (integer) or null The timestamp of the work end time in seconds since 1970-01-01 in the user's timezone. Meaning if the record end is supposed to be 2020-04-04 15:10 in New York, then the unix timestamp for 2020-04-04 15:10 UTC shall be sent.
	unix (integer) or null The timestamp of the work start time, rounded according to the 'billingRoundingMinutes'-setting. If not set and workTimeStart is given, this value will be set accordingly.
	unix (integer) or null The timestamp of the work end time, rounded according to the 'billingRoundingMinutes'-setting. If not set and workTimeEnd is given, this value will be set accordingly.
message	string <= 5000 characters The user's message of what he/she did.
isJourney	boolean Default: false Whether or not the recorded work time is a trip to the place of work.
	uuid (string) or null The UUID of the referenced node. This must be a work package or sub work package. This supersedes the `workPackage` property.
	uuid (string) or null The UUID of the associated work package. Superseded by the `referenceNode` property if supplied: This will always be the (parent) work package of the `referenceNode`.
	uuid (string) or null The UUID of the price category in case the work package requires an individual one per record.
	uuid (string) or null The UUID of the associated price surcharge.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the record.
user required	string^[0-9A-F]{32}$ The UUID of the user. Must be a regular user.

Responses

Request samples

Payload

Content type

application/json

{"workTimeStart": 1586004000,
"workTimeEnd": 1586005800,
"billingStart": 1586003400,
"billingEnd": 1586006100,
"message": "Briefing about Octaved Flow",
"isJourney": false,
"referenceNode": "E9996334F8134DBCBE18948284698BB2",
"workPackage": "E9996334F8134DBCBE18948284698BB2",
"priceCategory": "E9996334F8134DBCBE18948284698BB2",
"priceSurcharge": "E9996334F8134DBCBE18948284698BB2",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"user": "E9996334F8134DBCBE18948284698BB2"
}

Response samples

201

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Get time tracking record

path Parameters

timeTrackingRecordId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the time tracking record

Responses

Response samples

200

Content type

application/json

{"billedOn": 1586003400,
"id": "E9996334F8134DBCBE18948284698BB2",
"user": "E9996334F8134DBCBE18948284698BB2",
"workTimeStart": 1586004000,
"workTimeEnd": 1586005800,
"billingStart": 1586003400,
"billingEnd": 1586006100,
"message": "Briefing about Octaved Flow",
"isJourney": false,
"referenceNode": "E9996334F8134DBCBE18948284698BB2",
"workPackage": "E9996334F8134DBCBE18948284698BB2",
"priceCategory": "E9996334F8134DBCBE18948284698BB2",
"priceSurcharge": "E9996334F8134DBCBE18948284698BB2",
"labels": ["E9996334F8134DBCBE18948284698BB2"
]
}

Put time tracking record

path Parameters

timeTrackingRecordId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the time tracking record

Request Body schema: application/json
required

	unix (integer) or null The timestamp of the work start time in seconds since 1970-01-01 in the user's timezone. Meaning if the record start is supposed to be 2020-04-04 14:40 in New York, then the unix timestamp for 2020-04-04 14:40 UTC shall be sent.
	unix (integer) or null The timestamp of the work end time in seconds since 1970-01-01 in the user's timezone. Meaning if the record end is supposed to be 2020-04-04 15:10 in New York, then the unix timestamp for 2020-04-04 15:10 UTC shall be sent.
	unix (integer) or null The timestamp of the work start time, rounded according to the 'billingRoundingMinutes'-setting. If not set and workTimeStart is given, this value will be set accordingly.
	unix (integer) or null The timestamp of the work end time, rounded according to the 'billingRoundingMinutes'-setting. If not set and workTimeEnd is given, this value will be set accordingly.
message	string <= 5000 characters The user's message of what he/she did.
isJourney	boolean Default: false Whether or not the recorded work time is a trip to the place of work.
	uuid (string) or null The UUID of the referenced node. This must be a work package or sub work package. This supersedes the `workPackage` property.
	uuid (string) or null The UUID of the associated work package. Superseded by the `referenceNode` property if supplied: This will always be the (parent) work package of the `referenceNode`.
	uuid (string) or null The UUID of the price category in case the work package requires an individual one per record.
	uuid (string) or null The UUID of the associated price surcharge.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the record.
user required	string^[0-9A-F]{32}$ The UUID of the user. Must be a regular user.

Responses

Request samples

Payload

Content type

application/json

{"workTimeStart": 1586004000,
"workTimeEnd": 1586005800,
"billingStart": 1586003400,
"billingEnd": 1586006100,
"message": "Briefing about Octaved Flow",
"isJourney": false,
"referenceNode": "E9996334F8134DBCBE18948284698BB2",
"workPackage": "E9996334F8134DBCBE18948284698BB2",
"priceCategory": "E9996334F8134DBCBE18948284698BB2",
"priceSurcharge": "E9996334F8134DBCBE18948284698BB2",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"user": "E9996334F8134DBCBE18948284698BB2"
}

Patch time tracking record

path Parameters

timeTrackingRecordId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the time tracking record

Request Body schema: application/json
required

	unix (integer) or null The timestamp of the work start time in seconds since 1970-01-01 in the user's timezone. Meaning if the record start is supposed to be 2020-04-04 14:40 in New York, then the unix timestamp for 2020-04-04 14:40 UTC shall be sent.
	unix (integer) or null The timestamp of the work end time in seconds since 1970-01-01 in the user's timezone. Meaning if the record end is supposed to be 2020-04-04 15:10 in New York, then the unix timestamp for 2020-04-04 15:10 UTC shall be sent.
	unix (integer) or null The timestamp of the work start time, rounded according to the 'billingRoundingMinutes'-setting. If not set and workTimeStart is given, this value will be set accordingly.
	unix (integer) or null The timestamp of the work end time, rounded according to the 'billingRoundingMinutes'-setting. If not set and workTimeEnd is given, this value will be set accordingly.
message	string <= 5000 characters The user's message of what he/she did.
isJourney	boolean Default: false Whether or not the recorded work time is a trip to the place of work.
	uuid (string) or null The UUID of the referenced node. This must be a work package or sub work package. This supersedes the `workPackage` property.
	uuid (string) or null The UUID of the associated work package. Superseded by the `referenceNode` property if supplied: This will always be the (parent) work package of the `referenceNode`.
	uuid (string) or null The UUID of the price category in case the work package requires an individual one per record.
	uuid (string) or null The UUID of the associated price surcharge.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the record.
user	string^[0-9A-F]{32}$ The UUID of the user. Must be a regular user.

Responses

Request samples

Payload

Content type

application/json

{"workTimeStart": 1586004000,
"workTimeEnd": 1586005800,
"billingStart": 1586003400,
"billingEnd": 1586006100,
"message": "Briefing about Octaved Flow",
"isJourney": false,
"referenceNode": "E9996334F8134DBCBE18948284698BB2",
"workPackage": "E9996334F8134DBCBE18948284698BB2",
"priceCategory": "E9996334F8134DBCBE18948284698BB2",
"priceSurcharge": "E9996334F8134DBCBE18948284698BB2",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"user": "E9996334F8134DBCBE18948284698BB2"
}

Delete time tracking record

path Parameters

timeTrackingRecordId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the time tracking record

Responses

Simple search

Use one ident/value pair to search for a list of time tracking record ids.
See the request body section for a list of supported search idents.

If you provide yieldObjects as query parameter, the response will contain the time record objects instead of ids.

path Parameters

ident required	string
value	string The content/format depends on the search ident.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: Supported search idents and their values
required

customerId	string^[0-9A-F]{32}$ Finds all time tracking records made for a customer.
date	string^20[0-9]{2}-[0-9]{2}-[0-9]{2}$ Finds time tracking records at the given date.
dateRange	string^20[0-9]{2}-[0-9]{2}-[0-9]{2}-20[0-9]{2}-[0-9... Finds time tracking records at the given date range.
isBilled	any Finds time tracking records marked as billed. The value is not required.
isJourney	any Finds time tracking records marked as journey. The value is not required.
isOpen	any Finds time tracking records without an end date. The value is not required.
rootNodeId	string^[0-9A-F]{32}$ Finds all time tracking records beneath the given root node id, like a project/group/work package id.
userGroupId	string^[0-9A-F]{32}$ Finds time tracking records for users in the given user group id. This includes users in sub groups.
userId	string^[0-9A-F]{32}$ Finds time tracking records for the given user id.
referenceNodeId	string^[0-9A-F]{32}$ Finds time tracking records for the given reference node id, which is the node the record was made for. This can be a work package or sub work package.
workPackageId	string^[0-9A-F]{32}$ Finds time tracking records for the given work package id.

Responses

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Complex search

Use "and"-, "or"- or "not"-objects to assemble the desired search query. E.g.:

{"and":[{"ident":"propertyA","value":"foo"},{"or":[{"ident":"isOfSomeKindX"},{"ident":"propertyB","value":"bar"}]},{"not":{"ident":"isOfSomeKindY"}}]}

See the simple search request for the supported search idents.

If you provide yieldObjects as query parameter, the response will contain the time record objects instead of ids.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: application/json
required

One of

ident required	string non-empty
value	string

Responses

Request samples

Payload

Content type

application/json

Example

condition

{"ident": "string",
"value": "string"
}

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Billings REST

REST routes for billings

Get billings by ids

query Parameters

ids[] required	Array of strings (uuidArray) [^[0-9A-F]{32}$] Example: ids[]=E9996334F8134DBCBE18948284698BB2 UUIDs of the billings
withSums	string Value: "1" Includes some calculated sums in the response
withTimeRecordIds	string Value: "1" Includes the time record ids in the response
withWorkPackageIds	string Value: "1" Includes the work package ids in the response

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"createdOn": 1580555700,
"createdBy": "E9996334F8134DBCBE18948284698BB2",
"projectId": "E9996334F8134DBCBE18948284698BB2",
"customerId": "E9996334F8134DBCBE18948284698BB2",
"journeyBillingMode": "flatRate",
"flatRateJourneyPrice": 0,
"pricingSnapshot": {"flatRateJourneyPrice": 0,
"journeyBillingMode": "flatRate",
"priceCategories": { },
"priceSurcharges": { },
"sums": {"contingentPriceSum": 0,
"effortHoursSum": 0,
"effortPriceSum": 0,
"fixedPriceSum": 0,
"flatRateJourneyPriceSum": 0,
"numberOfFlatRateJourneys": 0,
"priceTotal": 0
},
"timeRecordPriceCategoryIds": { },
"timeRecordPriceSurchargeIds": { },
"workPackages": { }
},
"sums": {"contingentPriceSum": 0,
"effortHoursSum": 0,
"effortPriceSum": 0,
"fixedPriceSum": 0,
"flatRateJourneyPriceSum": 0,
"numberOfFlatRateJourneys": 0,
"priceTotal": 0
},
"timeRecordIds": ["E9996334F8134DBCBE18948284698BB2"
],
"workPackageIds": ["E9996334F8134DBCBE18948284698BB2"
],
"interval": "custom",
"intervalFrom": "2020-03-23",
"intervalTo": "2020-03-23",
"internalComment": "string",
"publicNote": "string",
"erpStatus": "none",
"erpReference": "string",
"erpMessage": "string",
"workflowStatus": "open"
}
]

Create billing

Creates a new billing instance.

Attaches all given work packages to it.

If an interval is given, attaches all time tracking records within that interval to it.

If no interval is given, attaches all time tracking records that have not been billed, yet.

Marks all attached time tracking records as billed.

Request Body schema: application/json
required

projectId required	string^[0-9A-F]{32}$ The project id for this billing.
workPackageIds required	Array of strings[^[0-9A-F]{32}$] Work packages to include in this billing. Only descendants of 'projectId' are included.
internalComment	string <= 5000 characters An internal comment, which is displayed in the UI.
publicNote	string <= 5000 characters A public note rendered in the PDF exports.
	BillingInterval (string) or null The interval for billing in period.
	date (string) or null The interval's from date for billing in period.
	date (string) or null The interval's inclusive end date for billing in period. E.g. for a month, this should be the last day of that month.

Responses

Request samples

Payload

Content type

application/json

{"projectId": "E9996334F8134DBCBE18948284698BB2",
"workPackageIds": ["E9996334F8134DBCBE18948284698BB2"
],
"internalComment": "string",
"publicNote": "string",
"interval": "custom",
"intervalFrom": "2020-03-23",
"intervalTo": "2020-03-23"
}

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Get billing

path Parameters

billingId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the billing

query Parameters

withSums	string Value: "1" Includes some calculated sums in the response
withTimeRecordIds	string Value: "1" Includes the time record ids in the response
withWorkPackageIds	string Value: "1" Includes the work package ids in the response

Responses

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2",
"createdOn": 1580555700,
"createdBy": "E9996334F8134DBCBE18948284698BB2",
"projectId": "E9996334F8134DBCBE18948284698BB2",
"customerId": "E9996334F8134DBCBE18948284698BB2",
"journeyBillingMode": "flatRate",
"flatRateJourneyPrice": 0,
"pricingSnapshot": {"flatRateJourneyPrice": 0,
"journeyBillingMode": "flatRate",
"priceCategories": { },
"priceSurcharges": { },
"sums": {"contingentPriceSum": 0,
"effortHoursSum": 0,
"effortPriceSum": 0,
"fixedPriceSum": 0,
"flatRateJourneyPriceSum": 0,
"numberOfFlatRateJourneys": 0,
"priceTotal": 0
},
"timeRecordPriceCategoryIds": { },
"timeRecordPriceSurchargeIds": { },
"workPackages": { }
},
"sums": {"contingentPriceSum": 0,
"effortHoursSum": 0,
"effortPriceSum": 0,
"fixedPriceSum": 0,
"flatRateJourneyPriceSum": 0,
"numberOfFlatRateJourneys": 0,
"priceTotal": 0
},
"timeRecordIds": ["E9996334F8134DBCBE18948284698BB2"
],
"workPackageIds": ["E9996334F8134DBCBE18948284698BB2"
],
"interval": "custom",
"intervalFrom": "2020-03-23",
"intervalTo": "2020-03-23",
"internalComment": "string",
"publicNote": "string",
"erpStatus": "none",
"erpReference": "string",
"erpMessage": "string",
"workflowStatus": "open"
}

Create billing with id

Creates a new billing instance.

Attaches all given work packages to it.

If an interval is given, attaches all time tracking records within that interval to it.

If no interval is given, attaches all time tracking records that have not been billed, yet.

Marks all attached time tracking records as billed.

path Parameters

billingId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the billing

Request Body schema: application/json
required

projectId required	string^[0-9A-F]{32}$ The project id for this billing.
workPackageIds required	Array of strings[^[0-9A-F]{32}$] Work packages to include in this billing. Only descendants of 'projectId' are included.
internalComment	string <= 5000 characters An internal comment, which is displayed in the UI.
publicNote	string <= 5000 characters A public note rendered in the PDF exports.
	BillingInterval (string) or null The interval for billing in period.
	date (string) or null The interval's from date for billing in period.
	date (string) or null The interval's inclusive end date for billing in period. E.g. for a month, this should be the last day of that month.

Responses

Request samples

Payload

Content type

application/json

{"projectId": "E9996334F8134DBCBE18948284698BB2",
"workPackageIds": ["E9996334F8134DBCBE18948284698BB2"
],
"internalComment": "string",
"publicNote": "string",
"interval": "custom",
"intervalFrom": "2020-03-23",
"intervalTo": "2020-03-23"
}

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Patch billing

path Parameters

billingId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the billing

Request Body schema: application/json
required

internalComment	string <= 5000 characters An internal comment, which is displayed in the UI.
publicNote	string <= 5000 characters A public note rendered in the PDF exports.
erpStatus	string Default: "none" Enum: "none" "transmittedFailed" "transmittedSuccessful" "processing" "processedWithWarning" "processedWithError" "processedSuccessful" The `transmitted` status are set by Octaved upon webhook transmission. Setting this status to any `process` is optional, it will be displayed in the UI.
erpReference	string <= 191 characters An optional reference value like an id on the erp side.
erpMessage	string An optional result message for e.g. warnings or error messages displayed in the UI.
workflowStatus	string Default: "open" Enum: "open" "hasIssues" "invoiced" The manual settable workflow status of the billing.

Responses

Request samples

Payload

Content type

application/json

{"internalComment": "string",
"publicNote": "string",
"erpStatus": "none",
"erpReference": "string",
"erpMessage": "string",
"workflowStatus": "open"
}

Delete billing

path Parameters

billingId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the billing

Responses

Simple search

Use one ident/value pair to search for a list of billing ids.
See the request body section for a list of supported search idents.
The resulting ids are sorted by creation date.

path Parameters

ident required	string See request body schema properties for the available idents.
value	string See request body schema for the appropriate type.

Request Body schema: Supported search idents and their values
required

createdInDateRange	string (dateRange) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}-20[0-9]{2}-[0-9...
customerId	string (uuid) ^[0-9A-F]{32}$
erpReference	string (varchar191) <= 191 characters
erpStatus	string (BillingErpStatus) Enum: "none" "transmittedFailed" "transmittedSuccessful" "processing" "processedWithWarning" "processedWithError" "processedSuccessful"
projectId	string (uuid) ^[0-9A-F]{32}$
timeTrackingRecordId	string (uuid) ^[0-9A-F]{32}$
workflowStatus	string (BillingWorkflowStatus) Enum: "open" "hasIssues" "invoiced"
workPackageId	string (uuid) ^[0-9A-F]{32}$

Responses

Response samples

200

Content type

application/json

["E9996334F8134DBCBE18948284698BB2"
]

Complex search

Use "and"-, "or"- or "not"-objects to assemble the desired search query. E.g.:

{"and":[{"ident":"propertyA","value":"foo"},{"or":[{"ident":"isOfSomeKindX"},{"ident":"propertyB","value":"bar"}]},{"not":{"ident":"isOfSomeKindY"}}]}

See the simple search request for the supported search idents.

Request Body schema: application/json
required

One of

ident required	string non-empty
value	string

Responses

Request samples

Payload

Content type

application/json

Example

condition

{"ident": "string",
"value": "string"
}

Response samples

200

Content type

application/json

["E9996334F8134DBCBE18948284698BB2"
]

Billings exports

Export routes for billings

JSON export v1 Deprecated

Deprecated - use "JSON export v2"

path Parameters

billingId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the billing

Responses

Response samples

200

Content type

application/json

{"billableHoursSum": 0,
"billablePrice": 0,
"billingId": "E9996334F8134DBCBE18948284698BB2",
"customer": {"customerNumber": "string",
"id": "E9996334F8134DBCBE18948284698BB2",
"name": "string"
},
"project": {"id": "E9996334F8134DBCBE18948284698BB2",
"name": "string"
},
"workHoursSum": 0,
"workPackages": [{"billableHoursSum": 0,
"billablePrice": 0,
"billingType": "contingent",
"fixedPrice": 0,
"hourlyRate": 0,
"id": "E9996334F8134DBCBE18948284698BB2",
"maxEffort": 0,
"name": "string",
"priceCategoryApiKey": "string",
"priceCategoryId": "string",
"surchargeHoursSum": 0,
"timeTrackingRecords": [{"billedOn": 1580555700,
"billingEnd": "23:59",
"billingStart": "23:59",
"date": "2020-03-23",
"hourlyRate": 0,
"id": "E9996334F8134DBCBE18948284698BB2",
"isJourney": false,
"message": "Briefing about Octaved Flow",
"priceCategoryApiKey": "string",
"priceCategoryId": "string",
"priceSurchargeApiKey": "string",
"priceSurchargeId": "E9996334F8134DBCBE18948284698BB2",
"priceSurchargePercentage": 0,
"userEmail": "string",
"userId": "E9996334F8134DBCBE18948284698BB2",
"workTimeEnd": "23:59",
"workTimeStart": "23:59"
}
],
"usePriceCategoryPerTimeTracking": true,
"workHoursSum": 0
}
]
}

JSON export v2

The response schema is identical to the one transmitted to the billing webhook (transmitBilling:v2)

path Parameters

billingId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the billing

Responses

Response samples

200

Content type

application/json

{"billingId": "E9996334F8134DBCBE18948284698BB2",
"customer": {"customerNumber": "string",
"id": "E9996334F8134DBCBE18948284698BB2",
"name": "string"
},
"flatRateJourneyPrice": 0,
"journeyBillingMode": "flatRate",
"priceTotal": 0,
"project": {"id": "E9996334F8134DBCBE18948284698BB2",
"name": "string"
},
"workPackages": [{"id": "E9996334F8134DBCBE18948284698BB2",
"name": "string",
"billingType": "contingent",
"usePriceCategoryPerTimeTracking": true,
"priceCategoryId": "string",
"priceCategoryApiKey": "string",
"hourlyRate": 0,
"fixedPrice": 0,
"contingentHours": 0,
"billableHoursWithoutJourneys": 0,
"billableHoursJourneys": 0,
"billableHoursTotal": 0,
"numberOfFlatRateJourneys": 0,
"priceBillableHoursTotalWithoutSurcharges": 0,
"priceFlatRateJourneys": 0,
"priceSurcharges": 0,
"priceTotal": 0,
"timeTrackingRecords": [{"billedOn": 1580555700,
"billingEnd": "23:59",
"billingStart": "23:59",
"date": "2020-03-23",
"hourlyRate": 0,
"id": "E9996334F8134DBCBE18948284698BB2",
"isJourney": false,
"message": "Briefing about Octaved Flow",
"priceCategoryApiKey": "string",
"priceCategoryId": "string",
"priceSurchargeApiKey": "string",
"priceSurchargeId": "E9996334F8134DBCBE18948284698BB2",
"priceSurchargePercentage": 0,
"userEmail": "string",
"userId": "E9996334F8134DBCBE18948284698BB2",
"workTimeEnd": "23:59",
"workTimeStart": "23:59"
}
]
}
]
}

CSV export

path Parameters

billingId required	string (uuid) ^[0-9A-F]{32}$ Example: E9996334F8134DBCBE18948284698BB2 UUID of the billing
type required	string Enum: "timeSheet" "sumsAndPrices"

Responses

Excel sums export

path Parameters

billingId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the billing

query Parameters

object (excelSums)

Configuration for included columns. Use json encoding: ?columns={"group":false}

Responses

Excel time sheet export

path Parameters

billingId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the billing

query Parameters

	object (excelTimeSheet) Configuration for included columns. Use json encoding: `?columns={"group":false}`
grouping	string (excelTimeSheetGrouping) Default: "none" Enum: "none" "byWorkPackage" "byWorkPackageAndUser" "bySubWorkPackage" Optionally groups time sheet by work package and user with respective sub totals

Responses

PDF time sheet export

path Parameters

billingId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the billing

query Parameters

	object (pdfTimeSheet) Configuration for included columns. Use json encoding: `?columns={"group":false}`
grouping	string (pdfTimeSheetGrouping) Default: "byWorkPackage" Enum: "byWorkPackage" "bySubWorkPackage" Optionally groups time sheet by sub work packages

Responses

Material resource folders

Routes for material resource folders

Gets material resource folders by ids

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the material resource folders

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"nodeType": "materialResourceFolder",
"name": "string"
}
]

Creates a material resource folder

Request Body schema: application/json
required

parentNodeId	string^[0-9A-F]{32}$ Default: "<root material resource folder id>" The UUID of the parent, which must be another material resource folder.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
name required	string (varchar191) <= 191 characters

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "<root material resource folder id>",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"name": "string"
}

Response samples

201

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Gets a material resource folder

path Parameters

materialResourceFolderId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the material resource folder

Responses

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"nodeType": "materialResourceFolder",
"name": "string"
}

Creates a material resource folder

path Parameters

materialResourceFolderId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the material resource folder

Request Body schema: application/json
required

parentNodeId	string^[0-9A-F]{32}$ Default: "<root material resource folder id>" The UUID of the parent, which must be another material resource folder.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
name required	string (varchar191) <= 191 characters

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "<root material resource folder id>",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"name": "string"
}

Patches a material resource folder

path Parameters

materialResourceFolderId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the material resource folder

Request Body schema: application/json
required

color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
name	string (varchar191) <= 191 characters

Responses

Request samples

Payload

Content type

application/json

{"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"name": "string"
}

Deletes a material resource folder

path Parameters

materialResourceFolderId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the material resource folder

Responses

Simple search

Use one ident/value pair to search for a list of material resource folder ids.
See the request body section for a list of supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

path Parameters

ident required	string
value	string The content/format depends on the search ident.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: Supported search idents and their values
required

ancestorsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all ancestor node ids in order, the direct parent first.
childrenOf	string (uuid) ^[0-9A-F]{32}$ A node id to find the direct child node ids.
descendantsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all descendant node ids (exclusive the given node id).
isArchived	string Value: "" No value used
labelId	string (uuid) ^[0-9A-F]{32}$ The id of the label to look for.
referenceNumber	string (varchar191) <= 191 characters
name	string non-empty

Responses

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Complex search

Use "and"-, "or"- or "not"-objects to assemble the desired search query. E.g.:

{"and":[{"ident":"propertyA","value":"foo"},{"or":[{"ident":"isOfSomeKindX"},{"ident":"propertyB","value":"bar"}]},{"not":{"ident":"isOfSomeKindY"}}]}

See the simple search request for the supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: application/json
required

One of

ident required	string non-empty
value	string

Responses

Request samples

Payload

Content type

application/json

Example

condition

{"ident": "string",
"value": "string"
}

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Material resources

Routes for material resources

Gets material resources by ids

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the material resources

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"nodeType": "materialResource",
"name": "string",
"isActive": true
}
]

Creates a material resource

Request Body schema: application/json
required

parentNodeId	string^[0-9A-F]{32}$ Default: "<root material resource folder id>" The UUID of the parent, which must be another material resource folder.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
name required	string (varchar191) <= 191 characters
isActive	boolean

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "<root material resource folder id>",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"name": "string",
"isActive": true
}

Response samples

201

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Gets a material resource

path Parameters

materialResourceId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the material resource

Responses

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2",
"isArchived": true,
"createdOn": 1580555700,
"lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
"lastChangedOn": 1580555700,
"parentNodeId": "E9996334F8134DBCBE18948284698BB2",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"nodeType": "materialResource",
"name": "string",
"isActive": true
}

Creates a material resource

path Parameters

materialResourceId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the material resource

Request Body schema: application/json
required

parentNodeId	string^[0-9A-F]{32}$ Default: "<root material resource folder id>" The UUID of the parent, which must be another material resource folder.
color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
name required	string (varchar191) <= 191 characters
isActive	boolean

Responses

Request samples

Payload

Content type

application/json

{"parentNodeId": "<root material resource folder id>",
"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"name": "string",
"isActive": true
}

Patches a material resource

path Parameters

materialResourceId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the material resource

Request Body schema: application/json
required

color	string <= 6 characters The color in hexadecimal notation.
labels	Array of strings[^[0-9A-F]{32}$] Ids of labels associated with the node.
	object <= 20 properties Stores your arbitrary data. Patches partially on top level. Any keys with a `null` value are removed. Each value may not exceed 20 kiB (json-serialized length).
referenceNumber	string (varchar191) <= 191 characters Your reference number for this node.
name	string (varchar191) <= 191 characters
isActive	boolean

Responses

Request samples

Payload

Content type

application/json

{"color": "7c9754",
"labels": ["E9996334F8134DBCBE18948284698BB2"
],
"keyValueStore": { },
"referenceNumber": "string",
"name": "string",
"isActive": true
}

Deletes a material resource

path Parameters

materialResourceId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

UUID of the material resource

Responses

Simple search

Use one ident/value pair to search for a list of material resource ids.
See the request body section for a list of supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

path Parameters

ident required	string
value	string The content/format depends on the search ident.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: Supported search idents and their values
required

ancestorsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all ancestor node ids in order, the direct parent first.
childrenOf	string (uuid) ^[0-9A-F]{32}$ A node id to find the direct child node ids.
descendantsOf	string (uuid) ^[0-9A-F]{32}$ A node id to find all descendant node ids (exclusive the given node id).
isArchived	string Value: "" No value used
labelId	string (uuid) ^[0-9A-F]{32}$ The id of the label to look for.
referenceNumber	string (varchar191) <= 191 characters
name	string non-empty

Responses

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Complex search

Use "and"-, "or"- or "not"-objects to assemble the desired search query. E.g.:

{"and":[{"ident":"propertyA","value":"foo"},{"or":[{"ident":"isOfSomeKindX"},{"ident":"propertyB","value":"bar"}]},{"not":{"ident":"isOfSomeKindY"}}]}

See the simple search request for the supported search idents.

If you provide yieldObjects as query parameter, the response will contain the objects instead of ids.

query Parameters

yieldObjects

string

Value: "1"

Request Body schema: application/json
required

One of

ident required	string non-empty
value	string

Responses

Request samples

Payload

Content type

application/json

Example

condition

{"ident": "string",
"value": "string"
}

Response samples

200

Content type

application/json

Example

uuidArray

[ ]

Organization users

Routes for organization users

Gets emails by user ids

Gets all user email addresses mapped by user ids. Optionally filters by specific user ids if provided as query parameter.

Note that system or api users have an empty email address - they are included anyway for verification purposes.

query Parameters

ids[]

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

Optionally filters the users by these ids.

Responses

Response samples

200

Content type

application/json

{"E9996334F8134DBCBE18948284698BB2": "max.mustermann@domain.de"
}

Current user

Who am I

Gets some details about the current identity and user.

Responses

Response samples

200

Content type

application/json

{"identity": {"id": "E9996334F8134DBCBE18948284698BB2",
"identifier": "string",
"email": "string",
"name": "string",
"organizations": {"invited": [{"organizationId": 0,
"organizationName": "string",
"userId": "E9996334F8134DBCBE18948284698BB2",
"userType": "string",
"isActive": true
}
],
"joined": [{"organizationId": 0,
"organizationName": "string",
"userId": "E9996334F8134DBCBE18948284698BB2",
"userType": "string",
"isActive": true
}
]
},
"websocket": {"jwt": "string",
"jwtExpiresAt": 0
}
},
"user": {"avatarUrl": "string",
"id": "E9996334F8134DBCBE18948284698BB2",
"name": "string",
"type": "api"
}
}

User groups

Working time tracking

Routes to read/write working time tracking

Get days

Gets the tracked working time for the given users/dates.

Optionally includes all working time entries with all of their revisions. Only the last revision of each entry counts towards the daily result. Thus the entry is considered deleted if its last revision is marked as isDeletion=true.

Optionally includes statistics for the week/month of a date.

If you are only interested in the monthly tracked working time, please request only the first date of the month and use includeStats=true. This will give you a sum for the month without having to load all the dates.

Request Body schema: application/json
required

dates required	Array of strings (dateArray) [^20[0-9]{2}-[0-9]{2}-[0-9]{2}$]
userIds required	Array of strings (uuidArray) [^[0-9A-F]{32}$]
includeEntries	boolean Optionally opt-in to receiving individual entries with all their revisions
includeStats	boolean Optionally opt-in to receiving `year`/`month`/`week` statistics

Responses

Request samples

Payload

Content type

application/json

{"dates": ["2020-03-23"
],
"userIds": ["E9996334F8134DBCBE18948284698BB2"
],
"includeEntries": true,
"includeStats": true
}

Response samples

200

Content type

application/json

[{"date": "2020-03-23",
"userId": "E9996334F8134DBCBE18948284698BB2",
"minutes": 0,
"warnings": ["germanyMissingBreak"
],
"entries": [{"id": "E9996334F8134DBCBE18948284698BB2",
"revisions": [{"createdBy": "E9996334F8134DBCBE18948284698BB2",
"createdOn": 1580555700,
"startDateTime": "2020-03-23 23:59:59",
"endDateTime": "2020-03-23 23:59:59",
"isDeletion": true
}
],
"userId": "E9996334F8134DBCBE18948284698BB2"
}
],
"week": {"minutes": 0
},
"month": {"minutes": 0
},
"year": {"minutes": 0
}
}
]

Add entry

Adds a single new working time entry

Request Body schema: application/json
required

startDateTime required	string^20[0-9]{2}-[0-9]{2}-[0-9]{2} ([0-1][0-9]\|2[0... The working time start, seconds are ignored
required	dateTime (string) or null The working time end, seconds are ignored. This must be on the same date as the startDateTime, unless it is exactly midnight of the next day. When editing for a different user or outside the days tolerance, the end time is also required.
userId required	string^[0-9A-F]{32}$ The user id for which this working time shall be recorded

Responses

Request samples

Payload

Content type

application/json

{"startDateTime": "2020-03-23 23:59:59",
"endDateTime": "2020-03-23 23:59:59",
"userId": "E9996334F8134DBCBE18948284698BB2"
}

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Get entry

Gets a single working time entry. Only the last revision counts. Thus this entry is considered deleted if its last revision is marked as isDeletion=true.

path Parameters

id

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

The id of the entry

Responses

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2",
"revisions": [{"createdBy": "E9996334F8134DBCBE18948284698BB2",
"createdOn": 1580555700,
"startDateTime": "2020-03-23 23:59:59",
"endDateTime": "2020-03-23 23:59:59",
"isDeletion": true
}
],
"userId": "E9996334F8134DBCBE18948284698BB2"
}

Add/update entry

Adds or updates a single working time entry. Each change creates a new revision.

path Parameters

id

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

The id of the entry

Request Body schema: application/json
required

startDateTime required	string^20[0-9]{2}-[0-9]{2}-[0-9]{2} ([0-1][0-9]\|2[0... The working time start, seconds are ignored
required	dateTime (string) or null The working time end, seconds are ignored. This must be on the same date as the startDateTime, unless it is exactly midnight of the next day. When editing for a different user or outside the days tolerance, the end time is also required.
userId required	string^[0-9A-F]{32}$ The user id for which this working time shall be recorded

Responses

Request samples

Payload

Content type

application/json

{"startDateTime": "2020-03-23 23:59:59",
"endDateTime": "2020-03-23 23:59:59",
"userId": "E9996334F8134DBCBE18948284698BB2"
}

Response samples

200

Content type

application/json

{"id": "E9996334F8134DBCBE18948284698BB2"
}

Delete entry

Marks an entry deleted by adding another revision with isDeletion=true. Entries cannot be deleted permanently.

path Parameters

id

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

The id of the entry

Responses

Add/update entries

Adds or updates multiple working time entries at once. Each change creates a new revision for its entry.

Request Body schema: application/json
required

required

Array of objects

Responses

Request samples

Payload

Content type

application/json

{"entries": [{"id": "string",
"startDateTime": "2020-03-23 23:59:59",
"endDateTime": "2020-03-23 23:59:59",
"userId": "E9996334F8134DBCBE18948284698BB2"
}
]
}

Response samples

200

Content type

application/json

{"ids": ["E9996334F8134DBCBE18948284698BB2"
]
}

Read working time

Routes to read the configured working time for the organization, groups and users

Get settings

Gets the working time settings for the given user/user group ids. Each result also includes all inherited settings. Settings "closer" to the user take precedence.

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the users or user groups to load the settings for

Responses

Response samples

200

Content type

application/json

[{"id": "E9996334F8134DBCBE18948284698BB2",
"weeklyWorkingTimes": [{"generations": [{"validFrom": "2020-03-23",
"workingMinutes": {"1": 480,
"2": 480,
"3": 480,
"4": 480,
"5": 480,
"6": 480,
"7": 480
},
"projectMinutes": {"1": 480,
"2": 480,
"3": 480,
"4": 480,
"5": 480,
"6": 480,
"7": 480
}
}
],
"pathLength": 0,
"definingUnitId": "E9996334F8134DBCBE18948284698BB2",
"definingUnitType": "organization"
}
],
"customWorkingTimes": [{"startDate": "2020-03-23",
"endDate": "2020-03-23",
"workingMinutes": 1440,
"projectMinutes": 1440,
"isNonStdWorkTime": true,
"type": "halfVacationDay",
"comment": "string",
"pathLength": 0,
"definingId": "E9996334F8134DBCBE18948284698BB2",
"definingUnitId": "E9996334F8134DBCBE18948284698BB2",
"definingUnitType": "organization"
}
],
"vacationConfigs": {"2023": {"entitlement": 30,
"carryover": 2.5
}
}
}
]

Get work minutes

Gets the resolved work minutes at specific days for users, taking any weekly or custom working time settings into account and resolving the inheritance.

The result is a record of every day within the requested date range mapping to a record of user ids to their work minutes at that day.

path Parameters

from required	string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$ Example: 2020-03-23 The start date for the date range to load
to required	string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$ Example: 2020-03-23 The end date for the date range to

query Parameters

ids[]

required

Array of strings (uuidArray) [^[0-9A-F]{32}$]

Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the users to load the work minutes for

Responses

Response samples

200

Content type

application/json

{"2020-02-13": {"E9996334F8134DBCBE18948284698BB2": 450
},
"2020-02-14": {"E9996334F8134DBCBE18948284698BB2": 0
}
}

Manage weekly working time

Routes to manage the regular weekly working time for the organization, groups and users.

The working time can be saved with a validFrom date, which we call "generations" of working times.

There must always be at least one generation on the organization/user/group to consider them having individual settings. Otherwise they inherit their working time from their closest parent group, the organization or the system.

While a generation is usually only used from its validFrom date onwards, a date not matching any generation will still use the settings from the earliest generation.

Set for organization

Adds or updates the weekly working time for the organization.

If the organization doesn't have any generations, calling this with a different validFrom than the default 2000-01-01 will cause the system default generation to be copied onto the organization. This is to not lose the effective existing settings. However, you can delete this copied generation again, but bare in mind that the generation with the lowest validFrom will also be used for any dates not matching any generation.

path Parameters

validFrom

string^20[0-9]{2}-[0-9]{2}-[0-9]{2}$

Default: "2000-01-01"

Example: 2020-03-23

The date from which the given weekly time shall be valid. If you don't work with generations of weekly working time, you can omit this, or use the default 2000-01-01.

Request Body schema: application/json
required

non-empty

	object The weekly working time in minutes. Used for working time tracking. If omitted, this will be set to the value of `projectMinutes`.
	object The weekly project time in minutes. Used for workload calculation in project planning. If omitted, this will be set to the value of `workingMinutes`.

Responses

Request samples

Payload

Content type

application/json

{"workingMinutes": {"1": 480,
"2": 480,
"3": 480,
"4": 480,
"5": 480,
"6": 480,
"7": 480
},
"projectMinutes": {"1": 480,
"2": 480,
"3": 480,
"4": 480,
"5": 480,
"6": 480,
"7": 480
}
}

Delete for organization

Deletes the weekly working time generation for the organization.

path Parameters

validFrom

string^20[0-9]{2}-[0-9]{2}-[0-9]{2}$

Default: "2000-01-01"

Example: 2020-03-23

The date from which the given weekly time shall be valid. If you don't work with generations of weekly working time, you can omit this, or use the default 2000-01-01.

Responses

Copy inheritance for group

This action copies all the inherited regular weekly working time generations onto the group. Use this if you want to switch the group to defining individual weekly working time without losing existing settings. Calling this method will only add generations that are not already defined for this group, so this can be used to merge with inherited generations later on.

path Parameters

groupId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

The id of the user group

Request Body schema: application/json
required

non-empty

	object The weekly working time in minutes. Used for working time tracking. If omitted, this will be set to the value of `projectMinutes`.
	object The weekly project time in minutes. Used for workload calculation in project planning. If omitted, this will be set to the value of `workingMinutes`.

Responses

Request samples

Payload

Content type

application/json

{"workingMinutes": {"1": 480,
"2": 480,
"3": 480,
"4": 480,
"5": 480,
"6": 480,
"7": 480
},
"projectMinutes": {"1": 480,
"2": 480,
"3": 480,
"4": 480,
"5": 480,
"6": 480,
"7": 480
}
}

Set for group

Adds or updates the weekly working time for the group

path Parameters

groupId required	string (uuid) ^[0-9A-F]{32}$ Example: E9996334F8134DBCBE18948284698BB2 The id of the user group
validFrom	string^20[0-9]{2}-[0-9]{2}-[0-9]{2}$ Default: "2000-01-01" Example: 2020-03-23 The date from which the given weekly time shall be valid. If you don't work with generations of weekly working time, you can omit this, or use the default `2000-01-01`.

Request Body schema: application/json
required

non-empty

	object The weekly working time in minutes. Used for working time tracking. If omitted, this will be set to the value of `projectMinutes`.
	object The weekly project time in minutes. Used for workload calculation in project planning. If omitted, this will be set to the value of `workingMinutes`.

Responses

Request samples

Payload

Content type

application/json

{"workingMinutes": {"1": 480,
"2": 480,
"3": 480,
"4": 480,
"5": 480,
"6": 480,
"7": 480
},
"projectMinutes": {"1": 480,
"2": 480,
"3": 480,
"4": 480,
"5": 480,
"6": 480,
"7": 480
}
}

Delete for group

Deletes the weekly working time for the group

path Parameters

groupId required	string (uuid) ^[0-9A-F]{32}$ Example: E9996334F8134DBCBE18948284698BB2 The id of the user group
validFrom	string^20[0-9]{2}-[0-9]{2}-[0-9]{2}$ Default: "2000-01-01" Example: 2020-03-23 The date from which the given weekly time shall be valid. If you don't work with generations of weekly working time, you can omit this, or use the default `2000-01-01`.

Responses

Delete all for group

Deletes all the weekly working time for the group, effectively making it inherit its settings again.

path Parameters

groupId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

The id of the user group

Responses

Copy inheritance for user

This action copies all the inherited regular weekly working time generations onto the user. Use this if you want to switch the user to defining individual weekly working time without losing existing settings. Calling this method will only add generations that are not already defined for this user, so this can be used to merge with inherited generations later on.

path Parameters

groupId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

The id of the user

Request Body schema: application/json
required

non-empty

	object The weekly working time in minutes. Used for working time tracking. If omitted, this will be set to the value of `projectMinutes`.
	object The weekly project time in minutes. Used for workload calculation in project planning. If omitted, this will be set to the value of `workingMinutes`.

Responses

Request samples

Payload

Content type

application/json

{"workingMinutes": {"1": 480,
"2": 480,
"3": 480,
"4": 480,
"5": 480,
"6": 480,
"7": 480
},
"projectMinutes": {"1": 480,
"2": 480,
"3": 480,
"4": 480,
"5": 480,
"6": 480,
"7": 480
}
}

Set for user

Adds or updates the weekly working time for the user

path Parameters

userId required	string (uuid) ^[0-9A-F]{32}$ Example: E9996334F8134DBCBE18948284698BB2 The id of the user
validFrom	string^20[0-9]{2}-[0-9]{2}-[0-9]{2}$ Default: "2000-01-01" Example: 2020-03-23 The date from which the given weekly time shall be valid. If you don't work with generations of weekly working time, you can omit this, or use the default `2000-01-01`.

Request Body schema: application/json
required

non-empty

	object The weekly working time in minutes. Used for working time tracking. If omitted, this will be set to the value of `projectMinutes`.
	object The weekly project time in minutes. Used for workload calculation in project planning. If omitted, this will be set to the value of `workingMinutes`.

Responses

Request samples

Payload

Content type

application/json

{"workingMinutes": {"1": 480,
"2": 480,
"3": 480,
"4": 480,
"5": 480,
"6": 480,
"7": 480
},
"projectMinutes": {"1": 480,
"2": 480,
"3": 480,
"4": 480,
"5": 480,
"6": 480,
"7": 480
}
}

Delete for user

Deletes the weekly working time for the user

path Parameters

userId required	string (uuid) ^[0-9A-F]{32}$ Example: E9996334F8134DBCBE18948284698BB2 The id of the user
validFrom	string^20[0-9]{2}-[0-9]{2}-[0-9]{2}$ Default: "2000-01-01" Example: 2020-03-23 The date from which the given weekly time shall be valid. If you don't work with generations of weekly working time, you can omit this, or use the default `2000-01-01`.

Responses

Delete all for user

Deletes all the weekly working time for the user, effectively making them inherit their settings again.

path Parameters

groupId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

The id of the user

Responses

Manage custom working time

Routes to manage the custom working time like off-days, sick leave or deviating working time

Set for organization

Adds or updates custom working time for the organiization

path Parameters

workTimeId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

The id for the custom work time. Generate a new UUID for a new entry (formatted to upper case w/o dashes).

Request Body schema: application/json
required

startDate required	string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
endDate required	string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
hours	number [ 0 .. 24 ] Deprecated Default: 0 Deprecated - use `workingMinutes`/`projectMinutes` instead to avoid decimal rounding problems
minutes	integer [ 0 .. 1440 ] Deprecated Default: 0 Deprecated - use `workingMinutes`/`projectMinutes`.
workingMinutes	integer [ 0 .. 1440 ] Default: 0 Used for working time tracking. For off-days this is 0. For partial sick leaves this should be set to the exact tracked working time of the day to have zero overtime. If omitted and a `projectMinutes` is set, the `projectMinutes` will be used, otherwise this defaults to `0`.
projectMinutes	integer [ 0 .. 1440 ] Used for workload calculation in project planning. If omitted, this will be set to the value of `workingMinutes`.
comment	string
type required	string Enum: "nonStandardWorkTime" "publicHoliday"

Responses

Request samples

Payload

Content type

application/json

{"startDate": "2020-03-23",
"endDate": "2020-03-23",
"hours": 0,
"minutes": 0,
"workingMinutes": 0,
"projectMinutes": 1440,
"comment": "string",
"type": "nonStandardWorkTime"
}

Set for group

Adds or updates custom work time for a user group

path Parameters

userGroupId required	string (uuid) ^[0-9A-F]{32}$ Example: E9996334F8134DBCBE18948284698BB2 The id of the user group
workTimeId required	string (uuid) ^[0-9A-F]{32}$ Example: E9996334F8134DBCBE18948284698BB2 The id for the custom work time. Generate a new UUID for a new entry (formatted to upper case w/o dashes).

Request Body schema: application/json
required

startDate required	string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
endDate required	string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
hours	number [ 0 .. 24 ] Deprecated Default: 0 Deprecated - use `workingMinutes`/`projectMinutes` instead to avoid decimal rounding problems
minutes	integer [ 0 .. 1440 ] Deprecated Default: 0 Deprecated - use `workingMinutes`/`projectMinutes`.
workingMinutes	integer [ 0 .. 1440 ] Default: 0 Used for working time tracking. For off-days this is 0. For partial sick leaves this should be set to the exact tracked working time of the day to have zero overtime. If omitted and a `projectMinutes` is set, the `projectMinutes` will be used, otherwise this defaults to `0`.
projectMinutes	integer [ 0 .. 1440 ] Used for workload calculation in project planning. If omitted, this will be set to the value of `workingMinutes`.
comment	string
type required	string Enum: "nonStandardWorkTime" "publicHoliday"

Responses

Request samples

Payload

Content type

application/json

{"startDate": "2020-03-23",
"endDate": "2020-03-23",
"hours": 0,
"minutes": 0,
"workingMinutes": 0,
"projectMinutes": 1440,
"comment": "string",
"type": "nonStandardWorkTime"
}

Set for user

Adds or updates custom working time for a user

path Parameters

userId required	string (uuid) ^[0-9A-F]{32}$ Example: E9996334F8134DBCBE18948284698BB2 The id of the user
workTimeId required	string (uuid) ^[0-9A-F]{32}$ Example: E9996334F8134DBCBE18948284698BB2 The id for the custom work time. Generate a new UUID for a new entry (formatted to upper case w/o dashes).

Request Body schema: application/json
required

startDate required	string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
endDate required	string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
hours	number [ 0 .. 24 ] Deprecated Default: 0 Deprecated - use `workingMinutes`/`projectMinutes` instead to avoid decimal rounding problems
minutes	integer [ 0 .. 1440 ] Deprecated Default: 0 Deprecated - use `workingMinutes`/`projectMinutes`.
workingMinutes	integer [ 0 .. 1440 ] Default: 0 Used for working time tracking. For off-days this is 0. For partial sick leaves this should be set to the exact tracked working time of the day to have zero overtime. If omitted and a `projectMinutes` is set, the `projectMinutes` will be used, otherwise this defaults to `0`.
projectMinutes	integer [ 0 .. 1440 ] Used for workload calculation in project planning. If omitted, this will be set to the value of `workingMinutes`.
comment	string
type required	string Enum: "halfVacationDay" "nonStandardWorkTime" "offDayOther" "partialSickLeave" "sickLeave" "vacationDay"

Responses

Request samples

Payload

Content type

application/json

{"startDate": "2020-03-23",
"endDate": "2020-03-23",
"hours": 0,
"minutes": 0,
"workingMinutes": 0,
"projectMinutes": 1440,
"comment": "string",
"type": "halfVacationDay"
}

Delete

Deletes a custom working time entry

path Parameters

workTimeId

required

string (uuid) ^[0-9A-F]{32}$

Example: E9996334F8134DBCBE18948284698BB2

The id of the custom work time

Responses

Manage vacation days

Routes to save vacation entitlement and carryover

Apply carryover (org)

Calculates the remaining days of the year before targetYear and those as carryover for targetYear for the entire organization.

path Parameters

targetYear

required

string^(1|2)[0-9]{3}$

Example: 2024

Customers

Gets customers

query Parameters

Responses

Response samples

Creates a customer

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Gets one customer

path Parameters

Responses

Response samples

Creates a customer

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Patches a customer

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Deletes a customer

path Parameters

Responses

Simple search

path Parameters

Request Body schema: Supported search idents and their valuesrequired

Responses

Response samples

Complex search

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Labels

Get all labels

Responses

Response samples

Create a label

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Create a label

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Patches a label

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Deletes a label

path Parameters

Responses

General

Gets nodes by ids

query Parameters

Responses

Response samples

Gets a node

path Parameters

Responses

Response samples

Simple search

path Parameters

query Parameters

Request Body schema: Supported search idents and their valuesrequired

Responses

Response samples

Complex search

query Parameters

Request Body schema: application/jsonrequired

Responses

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: Supported search idents and their values
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: Supported search idents and their values
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: Supported search idents and their values
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required