Octaved Flow (v1)

Download OpenAPI specification:Download

Documentation for the Octaved Flow API

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"
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"
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"
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"
]

General

General routes for all node types

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.

keyValueStore
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
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,
  • "lastChanged": 1580555700,
  • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
  • "lastChangedOn": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "nodeType": "projectFolder",
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "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.

keyValueStore
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
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.

keyValueStore
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
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^[0-9A-F]{32}$

A node id to find all ancestor node ids in order, the direct parent first.

childrenOf
string^[0-9A-F]{32}$

A node id to find the direct child node ids.

descendantsOf
string^[0-9A-F]{32}$

A node id to find all descendant node ids (exclusive the given node id).

isArchived
string
Value: ""

No value used

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^[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.

keyValueStore
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
description
string <= 5000 characters

The description.

name
required
string <= 191 characters

The name.

flowCustomer
required
string^[0-9A-F]{32}$

The UUID of the customer.

isLocked
boolean
Default: false

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.

status
string
Deprecated
Default: "open"
Enum: "open" "locked" "template" "archived"

Deprecated - use the flags isArchived/isLocked/isTemplate

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.

(patch (patch (object) or patch (object) or patch (object))) or null (patchNullable)

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "<root project folder id>",
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "description": "string",
  • "name": "string",
  • "flowCustomer": "E9996334F8134DBCBE18948284698BB2",
  • "isLocked": false,
  • "isClosed": false,
  • "isTemplate": false,
  • "maxEffort": 125.5,
  • "enforceMaxEffort": true,
  • "showMaxEffortInDays": true,
  • "maxPrice": 125.5,
  • "status": "open",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "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,
  • "lastChanged": 1580555700,
  • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
  • "lastChangedOn": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "dueDate": "2020-03-23",
  • "nodeType": "project",
  • "timeControl": {
    },
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "description": "string",
  • "name": "string",
  • "flowCustomer": "E9996334F8134DBCBE18948284698BB2",
  • "isLocked": false,
  • "isClosed": false,
  • "isTemplate": false,
  • "maxEffort": 125.5,
  • "enforceMaxEffort": true,
  • "showMaxEffortInDays": true,
  • "maxPrice": 125.5,
  • "status": "open",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ]
}

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^[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.

keyValueStore
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
description
string <= 5000 characters

The description.

name
required
string <= 191 characters

The name.

flowCustomer
required
string^[0-9A-F]{32}$

The UUID of the customer.

isLocked
boolean
Default: false

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.

status
string
Deprecated
Default: "open"
Enum: "open" "locked" "template" "archived"

Deprecated - use the flags isArchived/isLocked/isTemplate

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.

(patch (patch (object) or patch (object) or patch (object))) or null (patchNullable)

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "<root project folder id>",
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "description": "string",
  • "name": "string",
  • "flowCustomer": "E9996334F8134DBCBE18948284698BB2",
  • "isLocked": false,
  • "isClosed": false,
  • "isTemplate": false,
  • "maxEffort": 125.5,
  • "enforceMaxEffort": true,
  • "showMaxEffortInDays": true,
  • "maxPrice": 125.5,
  • "status": "open",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "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.

keyValueStore
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
description
string <= 5000 characters

The description.

name
string <= 191 characters

The name.

flowCustomer
string^[0-9A-F]{32}$

The UUID of the customer.

isLocked
boolean
Default: false

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.

status
string
Deprecated
Default: "open"
Enum: "open" "locked" "template" "archived"

Deprecated - use the flags isArchived/isLocked/isTemplate

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.

(patch (patch (object) or patch (object) or patch (object))) or null (patchNullable)

Responses

Request samples

Content type
application/json
{
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "description": "string",
  • "name": "string",
  • "flowCustomer": "E9996334F8134DBCBE18948284698BB2",
  • "isLocked": false,
  • "isClosed": false,
  • "isTemplate": false,
  • "maxEffort": 125.5,
  • "enforceMaxEffort": true,
  • "showMaxEffortInDays": true,
  • "maxPrice": 125.5,
  • "status": "open",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "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^[0-9A-F]{32}$

A node id to find all ancestor node ids in order, the direct parent first.

childrenOf
string^[0-9A-F]{32}$

A node id to find the direct child node ids.

descendantsOf
string^[0-9A-F]{32}$

A node id to find all descendant node ids (exclusive the given node id).

isArchived
string
Value: ""

No value used

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
[ ]

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.

keyValueStore
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
description
string <= 5000 characters

The description.

name
required
string <= 191 characters

The name.

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

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.

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.

(patch (patch (object) or patch (object) or patch (object))) or null (patchNullable)

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "description": "string",
  • "name": "string",
  • "enforceMaxEffort": true,
  • "groupType": "group",
  • "isLocked": false,
  • "isClosed": false,
  • "maxEffort": 125.5,
  • "maxPrice": 125.5,
  • "showMaxEffortInDays": true,
  • "sortOrder": 0,
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "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,
  • "lastChanged": 1580555700,
  • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
  • "lastChangedOn": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "flowCustomer": "E9996334F8134DBCBE18948284698BB2",
  • "dueDate": "2020-03-23",
  • "nodeType": "group",
  • "projectId": "E9996334F8134DBCBE18948284698BB2",
  • "timeControl": {
    },
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "description": "string",
  • "name": "string",
  • "enforceMaxEffort": true,
  • "groupType": "group",
  • "isLocked": false,
  • "isClosed": false,
  • "maxEffort": 125.5,
  • "maxPrice": 125.5,
  • "showMaxEffortInDays": true,
  • "sortOrder": 0,
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ]
}

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.

keyValueStore
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
description
string <= 5000 characters

The description.

name
required
string <= 191 characters

The name.

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

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.

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.

(patch (patch (object) or patch (object) or patch (object))) or null (patchNullable)

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "description": "string",
  • "name": "string",
  • "enforceMaxEffort": true,
  • "groupType": "group",
  • "isLocked": false,
  • "isClosed": false,
  • "maxEffort": 125.5,
  • "maxPrice": 125.5,
  • "showMaxEffortInDays": true,
  • "sortOrder": 0,
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "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.

keyValueStore
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
description
string <= 5000 characters

The description.

name
string <= 191 characters

The name.

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

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.

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.

(patch (patch (object) or patch (object) or patch (object))) or null (patchNullable)

Responses

Request samples

Content type
application/json
{
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "description": "string",
  • "name": "string",
  • "enforceMaxEffort": true,
  • "groupType": "group",
  • "isLocked": false,
  • "isClosed": false,
  • "maxEffort": 125.5,
  • "maxPrice": 125.5,
  • "showMaxEffortInDays": true,
  • "sortOrder": 0,
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "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^[0-9A-F]{32}$

A node id to find all ancestor node ids in order, the direct parent first.

childrenOf
string^[0-9A-F]{32}$

A node id to find the direct child node ids.

descendantsOf
string^[0-9A-F]{32}$

A node id to find all descendant node ids (exclusive the given node id).

isArchived
string
Value: ""

No value used

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.

keyValueStore
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
description
string <= 5000 characters

The description.

name
required
string <= 191 characters

The name.

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

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.

Array of objects
Deprecated

Deprecated - role specific max efforts have been removed.

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.

status
string
Deprecated
Default: "open"
Enum: "offer" "notYetOpen" "open" "locked" "closed"

Deprecated - use the flags isApprovedForBilling/isLocked/isOffer

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.

(patch (patch (object) or patch (object) or patch (object))) or null (patchNullable)

Responses

Request samples

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

keyValueStore
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
description
string <= 5000 characters

The description.

name
required
string <= 191 characters

The name.

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

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.

Array of objects
Deprecated

Deprecated - role specific max efforts have been removed.

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.

status
string
Deprecated
Default: "open"
Enum: "offer" "notYetOpen" "open" "locked" "closed"

Deprecated - use the flags isApprovedForBilling/isLocked/isOffer

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.

(patch (patch (object) or patch (object) or patch (object))) or null (patchNullable)

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "description": "string",
  • "name": "string",
  • "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",
  • "roleMaxEfforts": [
    ],
  • "sortOrder": 0,
  • "status": "open",
  • "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.

keyValueStore
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
description
string <= 5000 characters

The description.

name
string <= 191 characters

The name.

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

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.

Array of objects
Deprecated

Deprecated - role specific max efforts have been removed.

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.

status
string
Deprecated
Default: "open"
Enum: "offer" "notYetOpen" "open" "locked" "closed"

Deprecated - use the flags isApprovedForBilling/isLocked/isOffer

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.

(patch (patch (object) or patch (object) or patch (object))) or null (patchNullable)

Responses

Request samples

Content type
application/json
{
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "description": "string",
  • "name": "string",
  • "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",
  • "roleMaxEfforts": [
    ],
  • "sortOrder": 0,
  • "status": "open",
  • "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^[0-9A-F]{32}$

A node id to find all ancestor node ids in order, the direct parent first.

childrenOf
string^[0-9A-F]{32}$

A node id to find the direct child node ids.

descendantsOf
string^[0-9A-F]{32}$

A node id to find all descendant node ids (exclusive the given node id).

isArchived
string
Value: ""

No value used

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

isOffer
string
Value: ""

No value used

status
string
Deprecated
Enum: "offer" "notYetOpen" "open" "locked" "closed"

Deprecated - use the flags isApprovedForBilling/isLocked/isOffer

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.

keyValueStore
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
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

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",
  • "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,
  • "lastChanged": 1580555700,
  • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
  • "lastChangedOn": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "completedBy": "E9996334F8134DBCBE18948284698BB2",
  • "completedOn": 1580555700,
  • "nodeType": "subWorkPackage",
  • "planningDates": [
    ],
  • "projectId": "E9996334F8134DBCBE18948284698BB2",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ],
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "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.

keyValueStore
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
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

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",
  • "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.

keyValueStore
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
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

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",
  • "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^[0-9A-F]{32}$

A node id to find all ancestor node ids in order, the direct parent first.

childrenOf
string^[0-9A-F]{32}$

A node id to find the direct child node ids.

descendantsOf
string^[0-9A-F]{32}$

A node id to find all descendant node ids (exclusive the given node id).

isArchived
string
Value: ""

No value used

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
[ ]

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.

keyValueStore
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
Array of objects
Deprecated

Deprecated - use responsibleUsers/responsibleGroups

description
string <= 5000 characters

The description of the task.

hasExternalAssignee
boolean
Deprecated

Deprecated - set definesOwnResponsible: true together with responsibleUsers: [] and responsibleGroups: [] to have nobody responsible

name
required
string (varchar191) <= 191 characters
decimal8dot2 (number) or null

The planned duration in hours.

sortOrder
integer
Default: 0

The zero-based sort order of the task within its direct parent.

status
string
Default: "open"
Enum: "open" "complete"
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.

Responses

Request samples

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

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,
  • "lastChanged": 1580555700,
  • "lastChangedBy": "E9996334F8134DBCBE18948284698BB2",
  • "lastChangedOn": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "completedBy": "E9996334F8134DBCBE18948284698BB2",
  • "completedOn": 1580555700,
  • "nodeType": "task",
  • "planningDates": [
    ],
  • "color": "7c9754",
  • "labels": [
    ],
  • "keyValueStore": { },
  • "referenceNumber": "string",
  • "assignedUnits": [
    ],
  • "description": "string",
  • "hasExternalAssignee": true,
  • "name": "string",
  • "plannedTime": 125.5,
  • "sortOrder": 0,
  • "status": "open",
  • "definesOwnResponsible": true,
  • "responsibleGroups": [ ],
  • "responsibleUsers": [ ]
}

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.

keyValueStore
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
Array of objects
Deprecated

Deprecated - use responsibleUsers/responsibleGroups

description
string <= 5000 characters

The description of the task.

hasExternalAssignee
boolean
Deprecated

Deprecated - set definesOwnResponsible: true together with responsibleUsers: [] and responsibleGroups: [] to have nobody responsible

name
required
string (varchar191) <= 191 characters
decimal8dot2 (number) or null

The planned duration in hours.

sortOrder
integer
Default: 0

The zero-based sort order of the task within its direct parent.

status
string
Default: "open"
Enum: "open" "complete"
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.

Responses

Request samples

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

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.

keyValueStore
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
Array of objects
Deprecated

Deprecated - use responsibleUsers/responsibleGroups

description
string <= 5000 characters

The description of the task.

hasExternalAssignee
boolean
Deprecated

Deprecated - set definesOwnResponsible: true together with responsibleUsers: [] and responsibleGroups: [] to have nobody responsible

name
string (varchar191) <= 191 characters
decimal8dot2 (number) or null

The planned duration in hours.

sortOrder
integer
Default: 0

The zero-based sort order of the task within its direct parent.

status
string
Default: "open"
Enum: "open" "complete"
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.

Responses

Request samples

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

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^[0-9A-F]{32}$

A node id to find all ancestor node ids in order, the direct parent first.

childrenOf
string^[0-9A-F]{32}$

A node id to find the direct child node ids.

descendantsOf
string^[0-9A-F]{32}$

A node id to find all descendant node ids (exclusive the given node id).

isArchived
string
Value: ""

No value used

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.

roleType
string
Deprecated
Enum: "projectManager" "executing" "supporting"

Deprecated - role types have been removed. Project roles are independant from the responsible users now (formerly executing-typed roles).

For backwards compatibility, roleType=executing has the same effect as responsible=1, roleType=projectManager has the same effect as projectManager=1 and roleType=supporting has the same effect as anyProjectRole=1

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.

user
required
string^[0-9A-F]{32}$

The UUID of the 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",
  • "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"
}

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.

user
required
string^[0-9A-F]{32}$

The UUID of the 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",
  • "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.

user
string^[0-9A-F]{32}$

The UUID of the 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",
  • "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
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.

userId
string^[0-9A-F]{32}$

Finds time tracking records for the given user id.

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"
    }

    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",<