logo
API docs by Redocly

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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "customerNumber": "string",
  • "defaultBillingType": null,
  • "journeyBillingMode": null,
  • "fileExportLanguage": "de",
  • "isLocked": false,
  • "isInternal": false,
  • "locations": [
    ],
  • "name": "string",
  • "requiresInternalCharge": false,
  • "priceCategoryOverrides": { },
  • "priceSurchargeOverrides": { },
  • "showSignatureFieldInPdfTimeSheets": true
}

Response samples

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

Content type
application/json
{
  • "id": "E9996334F8134DBCBE18948284698BB2",
  • "customerNumber": "string",
  • "defaultBillingType": null,
  • "journeyBillingMode": null,
  • "fileExportLanguage": "de",
  • "isLocked": false,
  • "isInternal": false,
  • "locations": [
    ],
  • "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

Content type
application/json
{
  • "customerNumber": "string",
  • "defaultBillingType": null,
  • "journeyBillingMode": null,
  • "fileExportLanguage": "de",
  • "isLocked": false,
  • "isInternal": false,
  • "locations": [
    ],
  • "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

Content type
application/json
{
  • "customerNumber": "string",
  • "defaultBillingType": null,
  • "journeyBillingMode": null,
  • "fileExportLanguage": "de",
  • "isLocked": false,
  • "isInternal": false,
  • "locations": [
    ],
  • "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

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

Content type
application/json
Example
{
  • "ident": "string",
  • "value": "string"
}

Response samples

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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "name": "string",
  • "translations": { },
  • "color": "7c9754",
  • "isActive": true,
  • "projectFolders": [
    ]
}

Response samples

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

Content type
application/json
{
  • "name": "string",
  • "translations": { },
  • "color": "7c9754",
  • "isActive": true,
  • "projectFolders": [
    ]
}

Response samples

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

Content type
application/json
{
  • "name": "string",
  • "translations": { },
  • "color": "7c9754",
  • "isActive": true,
  • "projectFolders": [
    ]
}

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

Content type
application/json
[
  • {
    }
]

Gets a node

path Parameters
nodeId
required
string (uuid) ^[0-9A-F]{32}$
Example: E9996334F8134DBCBE18948284698BB2

UUID of the node

Responses

Response samples

Content type
application/json
Example
{
  • "id": "E9996334F8134DBCBE18948284698BB2",
  • "isArchived": true,
  • "createdOn": 1580555700,
  • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
  • "lastChangedOn": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "color": "7c9754",
  • "labels": [
    ],
  • "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" "subWorkPackage" "task" "taskSection" "userNode" "workPackage"

Responses

Response samples

Content type
application/json
Example
[ ]

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

Content type
application/json
Example
{
  • "ident": "string",
  • "value": "string"
}

Response samples

Content type
application/json
Example
[ ]

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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "parentNodeId": "<root project folder id>",
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "name": "string"
}

Response samples

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

Content type
application/json
{
  • "id": "E9996334F8134DBCBE18948284698BB2",
  • "isArchived": true,
  • "createdOn": 1580555700,
  • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
  • "lastChangedOn": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "color": "7c9754",
  • "labels": [
    ],
  • "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

Content type
application/json
{
  • "parentNodeId": "<root project folder id>",
  • "color": "7c9754",
  • "labels": [
    ],
  • "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

Content type
application/json
{
  • "color": "7c9754",
  • "labels": [
    ],
  • "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

Content type
application/json
Example
[ ]

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

Content type
application/json
Example
{
  • "ident": "string",
  • "value": "string"
}

Response samples

Content type
application/json
Example
[ ]

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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "color": "7c9754",
  • "labels": [
    ],
  • "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": {
    }
}

Response samples

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

Content type
application/json
{
  • "id": "E9996334F8134DBCBE18948284698BB2",
  • "isArchived": true,
  • "createdOn": 1580555700,
  • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
  • "lastChangedOn": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "description": "string",
  • "name": "string",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "dueDate": "2020-03-23",
  • "nodeType": "project",
  • "timeControl": {
    },
  • "minMaxPlanningDateInSubtree": {
    },
  • "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

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "color": "7c9754",
  • "labels": [
    ],
  • "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": {
    }
}

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

Content type
application/json
{
  • "color": "7c9754",
  • "labels": [
    ],
  • "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": {
    }
}

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

Content type
application/json
Example
[ ]

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

Content type
application/json
Example
{
  • "ident": "string",
  • "value": "string"
}

Response samples

Content type
application/json
Example
[ ]

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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "color": "7c9754",
  • "labels": [
    ],
  • "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": {
    }
}

Response samples

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

Content type
application/json
{
  • "id": "E9996334F8134DBCBE18948284698BB2",
  • "isArchived": true,
  • "createdOn": 1580555700,
  • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
  • "lastChangedOn": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "description": "string",
  • "name": "string",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "flowCustomer": "E9996334F8134DBCBE18948284698BB2",
  • "dueDate": "2020-03-23",
  • "nodeType": "group",
  • "projectId": "E9996334F8134DBCBE18948284698BB2",
  • "timeControl": {
    },
  • "minMaxPlanningDateInSubtree": {
    },
  • "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

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "color": "7c9754",
  • "labels": [
    ],
  • "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": {
    }
}

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

Content type
application/json
{
  • "color": "7c9754",
  • "labels": [
    ],
  • "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": {
    }
}

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

Content type
application/json
Example
[ ]

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

Content type
application/json
Example
{
  • "ident": "string",
  • "value": "string"
}

Response samples

Content type
application/json
Example
[ ]

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

Content type
application/json
[
  • {
    }
]

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.

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

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "color": "7c9754",
  • "labels": [
    ],
  • "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": {
    }
}

Response samples

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

Content type
application/json
{
  • "id": "E9996334F8134DBCBE18948284698BB2",
  • "isArchived": true,
  • "createdOn": 1580555700,
  • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
  • "lastChangedOn": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "description": "string",
  • "name": "string",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "completedBy": "E9996334F8134DBCBE18948284698BB2",
  • "completedOn": 1580555700,
  • "flowCustomer": "E9996334F8134DBCBE18948284698BB2",
  • "nodeType": "workPackage",
  • "planningDates": [
    ],
  • "projectId": "E9996334F8134DBCBE18948284698BB2",
  • "timeControl": {
    },
  • "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.

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

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "color": "7c9754",
  • "labels": [
    ],
  • "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": {
    }
}

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.

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

Content type
application/json
{
  • "color": "7c9754",
  • "labels": [
    ],
  • "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": {
    }
}

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

Content type
application/json
Example
[ ]

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

Content type
application/json
Example
{
  • "ident": "string",
  • "value": "string"
}

Response samples

Content type
application/json
Example
[ ]

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

Content type
application/json
[
  • {
    }
]

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.

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

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

Response samples

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

Content type
application/json
{
  • "id": "E9996334F8134DBCBE18948284698BB2",
  • "isArchived": true,
  • "createdOn": 1580555700,
  • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
  • "lastChangedOn": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "completedBy": "E9996334F8134DBCBE18948284698BB2",
  • "completedOn": 1580555700,
  • "nodeType": "subWorkPackage",
  • "planningDates": [
    ],
  • "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.

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

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "color": "7c9754",
  • "labels": [
    ],
  • "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.

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

Content type
application/json
{
  • "color": "7c9754",
  • "labels": [
    ],
  • "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

Content type
application/json
Example
[ ]

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

Content type
application/json
Example
{
  • "ident": "string",
  • "value": "string"
}

Response samples

Content type
application/json
Example
[ ]

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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "name": "string",
  • "sortOrder": 0
}

Response samples

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

Content type
application/json
{
  • "id": "E9996334F8134DBCBE18948284698BB2",
  • "isArchived": true,
  • "createdOn": 1580555700,
  • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
  • "lastChangedOn": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "color": "7c9754",
  • "labels": [
    ],
  • "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

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "color": "7c9754",
  • "labels": [
    ],
  • "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

Content type
application/json
{
  • "color": "7c9754",
  • "labels": [
    ],
  • "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

Content type
application/json
Example
[ ]

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

Content type
application/json
Example
{
  • "ident": "string",
  • "value": "string"
}

Response samples

Content type
application/json
Example
[ ]

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

Content type
application/json
[
  • {
    }
]

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.

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)
Default: "open"
Enum: "open" "complete"

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "description": "string",
  • "name": "string",
  • "plannedTime": 125.5,
  • "sortOrder": 0,
  • "status": "open"
}

Response samples

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

Content type
application/json
{
  • "id": "E9996334F8134DBCBE18948284698BB2",
  • "isArchived": true,
  • "createdOn": 1580555700,
  • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
  • "lastChangedOn": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "completedBy": "E9996334F8134DBCBE18948284698BB2",
  • "completedOn": 1580555700,
  • "nodeType": "task",
  • "planningDates": [
    ],
  • "projectId": "E9996334F8134DBCBE18948284698BB2",
  • "description": "string",
  • "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.

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)
Default: "open"
Enum: "open" "complete"

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "description": "string",
  • "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.

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)
Default: "open"
Enum: "open" "complete"

Responses

Request samples

Content type
application/json
{
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "description": "string",
  • "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
name
string non-empty
status
string (EnumFlowTaskStatus)
Enum: "open" "complete"

Responses

Response samples

Content type
application/json
Example
[ ]

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

Content type
application/json
Example
{
  • "ident": "string",
  • "value": "string"
}

Response samples

Content type
application/json
Example
[ ]

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

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

Content type
application/json
[
  • {
    }
]

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

Content type
application/json
[
  • {
    }
]

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

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": [
    ],
  • "user": "E9996334F8134DBCBE18948284698BB2"
}

Response samples

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

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": [
    ]
}

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

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": [
    ],
  • "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

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": [
    ],
  • "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

Content type
application/json
Example
[ ]

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

Content type
application/json
Example
{
  • "ident": "string",
  • "value": "string"
}

Response samples

Content type
application/json
Example
[ ]

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

Content type
application/json
[
  • {
    }
]

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.

    EnumFlowBillingInterval (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

    Content type
    application/json
    {
    • "projectId": "E9996334F8134DBCBE18948284698BB2",
    • "workPackageIds": [
      ],
    • "internalComment": "string",
    • "publicNote": "string",
    • "interval": "custom",
    • "intervalFrom": "2020-03-23",
    • "intervalTo": "2020-03-23"
    }

    Response samples

    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

    Content type
    application/json
    {
    • "id": "E9996334F8134DBCBE18948284698BB2",
    • "createdOn": 1580555700,
    • "createdBy": "E9996334F8134DBCBE18948284698BB2",
    • "projectId": "E9996334F8134DBCBE18948284698BB2",
    • "customerId": "E9996334F8134DBCBE18948284698BB2",
    • "journeyBillingMode": "flatRate",
    • "flatRateJourneyPrice": 0,
    • "sums": {
      },
    • "timeRecordIds": [
      ],
    • "workPackageIds": [
      ],
    • "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.

    EnumFlowBillingInterval (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

    Content type
    application/json
    {
    • "projectId": "E9996334F8134DBCBE18948284698BB2",
    • "workPackageIds": [
      ],
    • "internalComment": "string",
    • "publicNote": "string",
    • "interval": "custom",
    • "intervalFrom": "2020-03-23",
    • "intervalTo": "2020-03-23"
    }

    Response samples

    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

    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

    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

    Content type
    application/json
    Example
    {
    • "ident": "string",
    • "value": "string"
    }

    Response samples

    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

    Content type
    application/json
    {
    • "billableHoursSum": 0,
    • "billablePrice": 0,
    • "billingId": "E9996334F8134DBCBE18948284698BB2",
    • "customer": {
      },
    • "project": {
      },
    • "workHoursSum": 0,
    • "workPackages": [
      ]
    }

    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

    Content type
    application/json
    {
    • "billingId": "E9996334F8134DBCBE18948284698BB2",
    • "customer": {
      },
    • "flatRateJourneyPrice": 0,
    • "journeyBillingMode": "flatRate",
    • "priceTotal": 0,
    • "project": {
      },
    • "workPackages": [
      ]
    }

    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

    Content type
    application/json
    [
    • {
      }
    ]

    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

    Content type
    application/json
    {
    • "parentNodeId": "<root material resource folder id>",
    • "color": "7c9754",
    • "labels": [
      ],
    • "keyValueStore": { },
    • "referenceNumber": "string",
    • "name": "string"
    }

    Response samples

    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

    Content type
    application/json
    {
    • "id": "E9996334F8134DBCBE18948284698BB2",
    • "isArchived": true,
    • "createdOn": 1580555700,
    • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
    • "lastChangedOn": 1580555700,
    • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
    • "color": "7c9754",
    • "labels": [
      ],
    • "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

    Content type
    application/json
    {
    • "parentNodeId": "<root material resource folder id>",
    • "color": "7c9754",
    • "labels": [
      ],
    • "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

    Content type
    application/json
    {
    • "color": "7c9754",
    • "labels": [
      ],
    • "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

    Content type
    application/json
    Example
    [ ]

    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

    Content type
    application/json
    Example
    {
    • "ident": "string",
    • "value": "string"
    }

    Response samples

    Content type
    application/json
    Example
    [ ]

    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

    Content type
    application/json
    [
    • {
      }
    ]

    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

    Content type
    application/json
    {
    • "parentNodeId": "<root material resource folder id>",
    • "color": "7c9754",
    • "labels": [
      ],
    • "keyValueStore": { },
    • "referenceNumber": "string",
    • "name": "string",
    • "isActive": true
    }

    Response samples

    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

    Content type
    application/json
    {
    • "id": "E9996334F8134DBCBE18948284698BB2",
    • "isArchived": true,
    • "createdOn": 1580555700,
    • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
    • "lastChangedOn": 1580555700,
    • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
    • "color": "7c9754",
    • "labels": [
      ],
    • "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

    Content type
    application/json
    {
    • "parentNodeId": "<root material resource folder id>",
    • "color": "7c9754",
    • "labels": [
      ],
    • "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

    Content type
    application/json
    {
    • "color": "7c9754",
    • "labels": [
      ],
    • "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

    Content type
    application/json
    Example
    [ ]

    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

    Content type
    application/json
    Example
    {
    • "ident": "string",
    • "value": "string"
    }

    Response samples

    Content type
    application/json
    Example
    [ ]

    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

    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

    Content type
    application/json
    {
    • "identity": {
      },
    • "user": {
      }
    }

    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

    Content type
    application/json
    {
    • "dates": [
      ],
    • "userIds": [
      ],
    • "includeEntries": true,
    • "includeStats": true
    }

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    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

    Content type
    application/json
    {
    • "startDateTime": "2020-03-23 23:59:59",
    • "endDateTime": "2020-03-23 23:59:59",
    • "userId": "E9996334F8134DBCBE18948284698BB2"
    }

    Response samples

    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

    Content type
    application/json
    {
    • "id": "E9996334F8134DBCBE18948284698BB2",
    • "revisions": [
      ],
    • "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

    Content type
    application/json
    {
    • "startDateTime": "2020-03-23 23:59:59",
    • "endDateTime": "2020-03-23 23:59:59",
    • "userId": "E9996334F8134DBCBE18948284698BB2"
    }

    Response samples

    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

    Content type
    application/json
    {
    • "entries": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "ids": [
      ]
    }

    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

    Content type
    application/json
    [
    • {
      }
    ]

    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

    Content type
    application/json
    {
    • "2020-02-13": {
      },
    • "2020-02-14": {
      }
    }

    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

    Content type
    application/json
    {
    • "workingMinutes": {
      },
    • "projectMinutes": {
      }
    }

    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

    Content type
    application/json
    {
    • "workingMinutes": {
      },
    • "projectMinutes": {
      }
    }

    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

    Content type
    application/json
    {
    • "workingMinutes": {
      },
    • "projectMinutes": {
      }
    }

    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

    Content type
    application/json
    {
    • "workingMinutes": {
      },
    • "projectMinutes": {
      }
    }

    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

    Content type
    application/json
    {
    • "workingMinutes": {
      },
    • "projectMinutes": {
      }
    }

    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

    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

    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

    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

    The target year

    Responses

    Apply carryover (group)

    Calculates the remaining days of the year before targetYear and those as carryover for targetYear for all users belonging to the given group (and its sub groups).

    path Parameters
    groupId
    required
    string (uuid) ^[0-9A-F]{32}$
    Example: E9996334F8134DBCBE18948284698BB2

    The group id

    targetYear
    required
    string^(1|2)[0-9]{3}$
    Example: 2024

    The target year

    Responses

    Copy entitlement (org)

    Copies the configured vacation entitlement from sourceYear to targetYear for the entire organization.

    path Parameters
    sourceYear
    required
    string^(1|2)[0-9]{3}$
    Example: 2023

    The source year

    targetYear
    required
    string^(1|2)[0-9]{3}$
    Example: 2024

    The target year

    Responses

    Copy entitlement (group)

    Copies the configured vacation entitlement from sourceYear to targetYear for all users belonging to the given group (and its sub groups).

    path Parameters
    groupId
    required
    string (uuid) ^[0-9A-F]{32}$
    Example: E9996334F8134DBCBE18948284698BB2

    The group id

    sourceYear
    required
    string^(1|2)[0-9]{3}$
    Example: 2023

    The source year

    targetYear
    required
    string^(1|2)[0-9]{3}$
    Example: 2024

    The target year

    Responses

    Set entitlement (org)

    Sets the vacation entitlement to the given days for the given year for the entire organization.

    path Parameters
    year
    required
    string^(1|2)[0-9]{3}$
    Example: 2023

    The year

    days
    required
    string^(\d{1,3}(\.5)?|-)$
    Example: 30

    The number of days

    Responses

    Set entitlement (group)

    Sets the vacation entitlement to the given days for the given year for all users belonging to the given group (and its sub groups).

    path Parameters
    groupId
    required
    string (uuid) ^[0-9A-F]{32}$
    Example: E9996334F8134DBCBE18948284698BB2

    The group id

    year
    required
    string^(1|2)[0-9]{3}$
    Example: 2023

    The year

    days
    required
    string^(\d{1,3}(\.5)?|-)$
    Example: 30

    The number of days

    Responses

    Set entitlement (user)

    Sets the vacation entitlement to the given days for the given year and user.

    path Parameters
    userId
    required
    string (uuid) ^[0-9A-F]{32}$
    Example: E9996334F8134DBCBE18948284698BB2

    The user id

    year
    required
    string^(1|2)[0-9]{3}$
    Example: 2023

    The year

    days
    required
    string^(\d{1,3}(\.5)?|-)$
    Example: 30

    The number of days

    Responses

    Set carryover (user)

    Sets the vacation carryover to the given days for the given year and user.

    path Parameters
    userId
    required
    string (uuid) ^[0-9A-F]{32}$
    Example: E9996334F8134DBCBE18948284698BB2

    The user id

    year
    required
    string^(1|2)[0-9]{3}$
    Example: 2023

    The year

    days
    required
    string^(\d{1,3}(\.5)?|-)$
    Example: 30

    The number of days

    Responses

    Connector Runner

    Routes relating to connector runners