logo
API docs by Redocly

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)
Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the customers

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a customer

Request Body schema: application/json
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.

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.

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,
  • "fileExportLanguage": "de",
  • "isLocked": false,
  • "isInternal": false,
  • "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,
  • "fileExportLanguage": "de",
  • "isLocked": false,
  • "isInternal": false,
  • "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
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.

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.

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,
  • "fileExportLanguage": "de",
  • "isLocked": false,
  • "isInternal": false,
  • "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
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.

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.

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,
  • "fileExportLanguage": "de",
  • "isLocked": false,
  • "isInternal": false,
  • "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
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
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"
]

Project folders

Routes for project folders

Gets project folders by ids

query Parameters
ids[]
required
Array of strings (uuidArray)
Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the project folders

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a project folder

Request Body schema: application/json
parentNodeId
string^[0-9A-F]{32}$
Default: "<root project folder id>"

The UUID of the parent, which must be another project folder.

labels
Array of strings

Ids of labels associated with the node.

name
required
string (varchar191) <= 191 characters

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "<root project folder id>",
  • "labels": [
    ],
  • "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",
  • "createdOn": 1580555700,
  • "lastChanged": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "nodeType": "projectFolder",
  • "labels": [
    ],
  • "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
parentNodeId
string^[0-9A-F]{32}$
Default: "<root project folder id>"

The UUID of the parent, which must be another project folder.

labels
Array of strings

Ids of labels associated with the node.

name
required
string (varchar191) <= 191 characters

Responses

Request samples

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

Ids of labels associated with the node.

name
string (varchar191) <= 191 characters

Responses

Request samples

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

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
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)
Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the projects

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a project

Request Body schema: application/json
parentNodeId
string^[0-9A-F]{32}$
Default: "<root project folder id>"

The UUID of the Flow-OU, where this project is to be created.

labels
Array of strings

Ids of labels associated with the node.

description
string <= 5000 characters

The description.

name
required
string <= 191 characters

The name.

color
string <= 6 characters

The color for the project icon in hexadecimal notation.

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

The UUID of the customer.

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.

showTimeControlAfterName
boolean
Default: true

If TRUE the project's time control date is displayed after the project's name.

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

The status of the project

timeControl
string
Default: "disabled"
Enum: "disabled" "monthly" "quarterly" "yearly" "custom"

The time control mode of the project

date (string) or null

The time control start date. This should be the first day in the relevant time frame. E.g. for a 'timeControl'-mode 'monthly', this should be the fist day of that month.

date (string) or null

The time control end date. Only used for the 'timeControl'-mode 'custom'.

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "<root project folder id>",
  • "labels": [
    ],
  • "description": "string",
  • "name": "string",
  • "color": "7c9754",
  • "flowCustomer": "E9996334F8134DBCBE18948284698BB2",
  • "maxEffort": 125.5,
  • "enforceMaxEffort": true,
  • "showMaxEffortInDays": true,
  • "maxPrice": 125.5,
  • "showTimeControlAfterName": true,
  • "status": "open",
  • "timeControl": "disabled",
  • "timeControlFrom": "2020-03-23",
  • "timeControlTo": "2020-03-23"
}

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",
  • "createdOn": 1580555700,
  • "lastChanged": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "dueDate": "2020-03-23",
  • "nodeType": "project",
  • "labels": [
    ],
  • "description": "string",
  • "name": "string",
  • "color": "7c9754",
  • "flowCustomer": "E9996334F8134DBCBE18948284698BB2",
  • "maxEffort": 125.5,
  • "enforceMaxEffort": true,
  • "showMaxEffortInDays": true,
  • "maxPrice": 125.5,
  • "showTimeControlAfterName": true,
  • "status": "open",
  • "timeControl": "disabled",
  • "timeControlFrom": "2020-03-23",
  • "timeControlTo": "2020-03-23"
}

Creates a project

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

UUID of the project

Request Body schema: application/json
parentNodeId
string^[0-9A-F]{32}$
Default: "<root project folder id>"

The UUID of the Flow-OU, where this project is to be created.

labels
Array of strings

Ids of labels associated with the node.

description
string <= 5000 characters

The description.

name
required
string <= 191 characters

The name.

color
string <= 6 characters

The color for the project icon in hexadecimal notation.

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

The UUID of the customer.

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.

showTimeControlAfterName
boolean
Default: true

If TRUE the project's time control date is displayed after the project's name.

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

The status of the project

timeControl
string
Default: "disabled"
Enum: "disabled" "monthly" "quarterly" "yearly" "custom"

The time control mode of the project

date (string) or null

The time control start date. This should be the first day in the relevant time frame. E.g. for a 'timeControl'-mode 'monthly', this should be the fist day of that month.

date (string) or null

The time control end date. Only used for the 'timeControl'-mode 'custom'.

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "<root project folder id>",
  • "labels": [
    ],
  • "description": "string",
  • "name": "string",
  • "color": "7c9754",
  • "flowCustomer": "E9996334F8134DBCBE18948284698BB2",
  • "maxEffort": 125.5,
  • "enforceMaxEffort": true,
  • "showMaxEffortInDays": true,
  • "maxPrice": 125.5,
  • "showTimeControlAfterName": true,
  • "status": "open",
  • "timeControl": "disabled",
  • "timeControlFrom": "2020-03-23",
  • "timeControlTo": "2020-03-23"
}

Patches a project

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

UUID of the project

Request Body schema: application/json
labels
Array of strings

Ids of labels associated with the node.

description
string <= 5000 characters

The description.

name
string <= 191 characters

The name.

color
string <= 6 characters

The color for the project icon in hexadecimal notation.

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

The UUID of the customer.

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.

showTimeControlAfterName
boolean
Default: true

If TRUE the project's time control date is displayed after the project's name.

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

The status of the project

timeControl
string
Default: "disabled"
Enum: "disabled" "monthly" "quarterly" "yearly" "custom"

The time control mode of the project

date (string) or null

The time control start date. This should be the first day in the relevant time frame. E.g. for a 'timeControl'-mode 'monthly', this should be the fist day of that month.

date (string) or null

The time control end date. Only used for the 'timeControl'-mode 'custom'.

Responses

Request samples

Content type
application/json
{
  • "labels": [
    ],
  • "description": "string",
  • "name": "string",
  • "color": "7c9754",
  • "flowCustomer": "E9996334F8134DBCBE18948284698BB2",
  • "maxEffort": 125.5,
  • "enforceMaxEffort": true,
  • "showMaxEffortInDays": true,
  • "maxPrice": 125.5,
  • "showTimeControlAfterName": true,
  • "status": "open",
  • "timeControl": "disabled",
  • "timeControlFrom": "2020-03-23",
  • "timeControlTo": "2020-03-23"
}

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

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
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)
Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the groups

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a group

Request Body schema: application/json
parentNodeId
required
string^[0-9A-F]{32}$

The UUID of the parent, which can be a project or a group.

sortedSiblingIds
Array of strings

Updates the sort orders of all sibling groups/work pacakges. Should include all sibling ids in order, including the new work package's id.

labels
Array of strings

Ids of labels associated with the node.

description
string <= 5000 characters

The description.

name
required
string <= 191 characters

The name.

color
string <= 6 characters

The color for the group in hexadecimal notation.

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.

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.

showTimeControlAfterName
boolean
Default: true

If TRUE the project's time control date is displayed after the project's name.

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.

timeControl
string
Default: "disabled"
Enum: "disabled" "monthly" "quarterly" "yearly" "custom"

The time control mode of the project

date (string) or null

The time control start date. This should be the first day in the relevant time frame. E.g. for a 'timeControl'-mode 'monthly', this should be the fist day of that month.

date (string) or null

The time control end date. Only used for the 'timeControl'-mode 'custom'.

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "labels": [
    ],
  • "description": "string",
  • "name": "string",
  • "color": "7c9754",
  • "enforceMaxEffort": true,
  • "groupType": "group",
  • "maxEffort": 125.5,
  • "maxPrice": 125.5,
  • "showMaxEffortInDays": true,
  • "showTimeControlAfterName": true,
  • "sortOrder": 0,
  • "timeControl": "disabled",
  • "timeControlFrom": "2020-03-23",
  • "timeControlTo": "2020-03-23"
}

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",
  • "createdOn": 1580555700,
  • "lastChanged": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "flowCustomer": "E9996334F8134DBCBE18948284698BB2",
  • "dueDate": "2020-03-23",
  • "nodeType": "group",
  • "projectId": "E9996334F8134DBCBE18948284698BB2",
  • "labels": [
    ],
  • "description": "string",
  • "name": "string",
  • "color": "7c9754",
  • "enforceMaxEffort": true,
  • "groupType": "group",
  • "maxEffort": 125.5,
  • "maxPrice": 125.5,
  • "showMaxEffortInDays": true,
  • "showTimeControlAfterName": true,
  • "sortOrder": 0,
  • "timeControl": "disabled",
  • "timeControlFrom": "2020-03-23",
  • "timeControlTo": "2020-03-23"
}

Creates a group

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

UUID of the group

Request Body schema: application/json
parentNodeId
required
string^[0-9A-F]{32}$

The UUID of the parent, which can be a project or a group.

sortedSiblingIds
Array of strings

Updates the sort orders of all sibling groups/work pacakges. Should include all sibling ids in order, including the new work package's id.

labels
Array of strings

Ids of labels associated with the node.

description
string <= 5000 characters

The description.

name
required
string <= 191 characters

The name.

color
string <= 6 characters

The color for the group in hexadecimal notation.

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.

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.

showTimeControlAfterName
boolean
Default: true

If TRUE the project's time control date is displayed after the project's name.

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.

timeControl
string
Default: "disabled"
Enum: "disabled" "monthly" "quarterly" "yearly" "custom"

The time control mode of the project

date (string) or null

The time control start date. This should be the first day in the relevant time frame. E.g. for a 'timeControl'-mode 'monthly', this should be the fist day of that month.

date (string) or null

The time control end date. Only used for the 'timeControl'-mode 'custom'.

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "labels": [
    ],
  • "description": "string",
  • "name": "string",
  • "color": "7c9754",
  • "enforceMaxEffort": true,
  • "groupType": "group",
  • "maxEffort": 125.5,
  • "maxPrice": 125.5,
  • "showMaxEffortInDays": true,
  • "showTimeControlAfterName": true,
  • "sortOrder": 0,
  • "timeControl": "disabled",
  • "timeControlFrom": "2020-03-23",
  • "timeControlTo": "2020-03-23"
}

Patches a group

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

UUID of the group

Request Body schema: application/json
labels
Array of strings

Ids of labels associated with the node.

description
string <= 5000 characters

The description.

name
string <= 191 characters

The name.

color
string <= 6 characters

The color for the group in hexadecimal notation.

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.

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.

showTimeControlAfterName
boolean
Default: true

If TRUE the project's time control date is displayed after the project's name.

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.

timeControl
string
Default: "disabled"
Enum: "disabled" "monthly" "quarterly" "yearly" "custom"

The time control mode of the project

date (string) or null

The time control start date. This should be the first day in the relevant time frame. E.g. for a 'timeControl'-mode 'monthly', this should be the fist day of that month.

date (string) or null

The time control end date. Only used for the 'timeControl'-mode 'custom'.

Responses

Request samples

Content type
application/json
{
  • "labels": [
    ],
  • "description": "string",
  • "name": "string",
  • "color": "7c9754",
  • "enforceMaxEffort": true,
  • "groupType": "group",
  • "maxEffort": 125.5,
  • "maxPrice": 125.5,
  • "showMaxEffortInDays": true,
  • "showTimeControlAfterName": true,
  • "sortOrder": 0,
  • "timeControl": "disabled",
  • "timeControlFrom": "2020-03-23",
  • "timeControlTo": "2020-03-23"
}

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

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
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)
Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the work packages

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a work package

Request Body schema: application/json
parentNodeId
required
string^[0-9A-F]{32}$

The UUID of the parent, which can be a project or a group.

sortedSiblingIds
Array of strings

Updates the sort orders of all sibling groups/work pacakges. Should include all sibling ids in order, including the new work package's id.

labels
Array of strings

Ids of labels associated with the node.

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.

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

Role specific max efforts.

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
Default: "open"
Enum: "offer" "notYetOpen" "open" "locked" "closed"

The status.

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.

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "labels": [
    ],
  • "description": "string",
  • "name": "string",
  • "billingType": "effort",
  • "effortFrom": 125.5,
  • "effortTo": 125.5,
  • "fixedPrice": 125.5,
  • "freeOfChargeReason": "service",
  • "isCompleted": false,
  • "maxEffort": 125.5,
  • "priceCategory": "E9996334F8134DBCBE18948284698BB2",
  • "roleMaxEfforts": [
    ],
  • "sortOrder": 0,
  • "status": "open",
  • "usePriceCategoryPerTimeTracking": false
}

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",
  • "createdOn": 1580555700,
  • "lastChanged": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "completedBy": "E9996334F8134DBCBE18948284698BB2",
  • "completedOn": 1580555700,
  • "flowCustomer": "E9996334F8134DBCBE18948284698BB2",
  • "nodeType": "workPackage",
  • "planningDates": [
    ],
  • "projectId": "E9996334F8134DBCBE18948284698BB2",
  • "labels": [
    ],
  • "description": "string",
  • "name": "string",
  • "billingType": "effort",
  • "effortFrom": 125.5,
  • "effortTo": 125.5,
  • "fixedPrice": 125.5,
  • "freeOfChargeReason": "service",
  • "isCompleted": false,
  • "maxEffort": 125.5,
  • "priceCategory": "E9996334F8134DBCBE18948284698BB2",
  • "roleMaxEfforts": [
    ],
  • "sortOrder": 0,
  • "status": "open",
  • "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
parentNodeId
required
string^[0-9A-F]{32}$

The UUID of the parent, which can be a project or a group.

sortedSiblingIds
Array of strings

Updates the sort orders of all sibling groups/work pacakges. Should include all sibling ids in order, including the new work package's id.

labels
Array of strings

Ids of labels associated with the node.

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.

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

Role specific max efforts.

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
Default: "open"
Enum: "offer" "notYetOpen" "open" "locked" "closed"

The status.

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.

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "labels": [
    ],
  • "description": "string",
  • "name": "string",
  • "billingType": "effort",
  • "effortFrom": 125.5,
  • "effortTo": 125.5,
  • "fixedPrice": 125.5,
  • "freeOfChargeReason": "service",
  • "isCompleted": false,
  • "maxEffort": 125.5,
  • "priceCategory": "E9996334F8134DBCBE18948284698BB2",
  • "roleMaxEfforts": [
    ],
  • "sortOrder": 0,
  • "status": "open",
  • "usePriceCategoryPerTimeTracking": false
}

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
labels
Array of strings

Ids of labels associated with the node.

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.

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

Role specific max efforts.

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
Default: "open"
Enum: "offer" "notYetOpen" "open" "locked" "closed"

The status.

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.

Responses

Request samples

Content type
application/json
{
  • "labels": [
    ],
  • "description": "string",
  • "name": "string",
  • "billingType": "effort",
  • "effortFrom": 125.5,
  • "effortTo": 125.5,
  • "fixedPrice": 125.5,
  • "freeOfChargeReason": "service",
  • "isCompleted": false,
  • "maxEffort": 125.5,
  • "priceCategory": "E9996334F8134DBCBE18948284698BB2",
  • "roleMaxEfforts": [
    ],
  • "sortOrder": 0,
  • "status": "open",
  • "usePriceCategoryPerTimeTracking": false
}

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

name
string non-empty
customerId
string (uuid) ^[0-9A-F]{32}$
status
string (EnumFlowWorkPackageStatus)
Enum: "offer" "notYetOpen" "open" "locked" "closed"

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
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)
Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the tasks

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a task

Request Body schema: application/json
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

Updates the sort orders of all sibling tasks. Should include all sibling ids in order, including the new task's id.

labels
Array of strings

Ids of labels associated with the node.

Array of objects

Directly assigned users/groups for this task. These take precedence over the assigned users/groups of the task's work package and can be used to assign only a single task to a different person.

description
string <= 5000 characters

The description of the task.

hasExternalAssignee
boolean
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"

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "labels": [
    ],
  • "assignedUnits": [
    ],
  • "description": "string",
  • "hasExternalAssignee": true,
  • "name": "string",
  • "plannedTime": 125.5,
  • "sortOrder": 0,
  • "status": "open"
}

Response samples

Content type
application/json
{
  • "id": "E9996334F8134DBCBE18948284698BB2"
}

Gets a task

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

UUID of the task

Responses

Response samples

Content type
application/json
{
  • "id": "E9996334F8134DBCBE18948284698BB2",
  • "createdOn": 1580555700,
  • "lastChanged": 1580555700,
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "completedBy": "E9996334F8134DBCBE18948284698BB2",
  • "completedOn": 1580555700,
  • "nodeType": "task",
  • "planningDates": [
    ],
  • "labels": [
    ],
  • "assignedUnits": [
    ],
  • "description": "string",
  • "hasExternalAssignee": true,
  • "name": "string",
  • "plannedTime": 125.5,
  • "sortOrder": 0,
  • "status": "open"
}

Creates a task

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

UUID of the task

Request Body schema: application/json
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

Updates the sort orders of all sibling tasks. Should include all sibling ids in order, including the new task's id.

labels
Array of strings

Ids of labels associated with the node.

Array of objects

Directly assigned users/groups for this task. These take precedence over the assigned users/groups of the task's work package and can be used to assign only a single task to a different person.

description
string <= 5000 characters

The description of the task.

hasExternalAssignee
boolean
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"

Responses

Request samples

Content type
application/json
{
  • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
  • "sortedSiblingIds": [
    ],
  • "labels": [
    ],
  • "assignedUnits": [
    ],
  • "description": "string",
  • "hasExternalAssignee": true,
  • "name": "string",
  • "plannedTime": 125.5,
  • "sortOrder": 0,
  • "status": "open"
}

Patches a task

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

UUID of the task

Request Body schema: application/json
labels
Array of strings

Ids of labels associated with the node.

Array of objects

Directly assigned users/groups for this task. These take precedence over the assigned users/groups of the task's work package and can be used to assign only a single task to a different person.

description
string <= 5000 characters

The description of the task.

hasExternalAssignee
boolean
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"

Responses

Request samples

Content type
application/json
{
  • "labels": [
    ],
  • "assignedUnits": [
    ],
  • "description": "string",
  • "hasExternalAssignee": true,
  • "name": "string",
  • "plannedTime": 125.5,
  • "sortOrder": 0,
  • "status": "open"
}

Deletes a task

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

UUID of the task

Responses

Simple search

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

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

path Parameters
ident
required
string
value
string

The content/format depends on the search ident.

query Parameters
yieldObjects
string
Value: "1"
Request Body schema: Supported search idents and their values
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).

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
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 responsible for a node. The response is a record of all requested node ids mapping to their respective responsible users.

Project role assignments of project role type "executing" are superseeded by direct assignments on tasks.

The result can be filtered by two optional query parameters roleId or roleType to get a more specific type of responsible users.

query Parameters
ids[]
required
Array of strings (uuidArray)
Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the nodes

roleId
string (uuid) ^[0-9A-F]{32}$
Example: roleId=E9996334F8134DBCBE18948284698BB2

UUID of a specific project role to filter for. If this role is of "executing" type, then it may still be superseeded by direct assignments on tasks.

roleType
string (EnumFlowProjectRoleType)
Enum: "projectManager" "executing" "supporting"

A specific project role type to filter for. Direct task assignments count as "executing" type.

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)
Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the nodes

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Time tracking records

Routes for time tracking records

Gets time tracking records by ids

query Parameters
ids[]
required
Array of strings (uuidArray)
Example: ids[]=E9996334F8134DBCBE18948284698BB2

UUIDs of the time tracking records

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Creates a time tracking record

Request Body schema: application/json
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 associated work package.

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 for which the time tracking record shall be created.

Responses

Request samples

Content type
application/json
{
  • "workTimeStart": 1586004000,
  • "workTimeEnd": 1586005800,
  • "billingStart": 1586003400,
  • "billingEnd": 1586006100,
  • "message": "Briefing about Octaved Flow",
  • "isJourney": false,
  • "workPackage": "E9996334F8134DBCBE18948284698BB2",
  • "priceCategory": "E9996334F8134DBCBE18948284698BB2",
  • "priceSurcharge": "E9996334F8134DBCBE18948284698BB2",
  • "user": "E9996334F8134DBCBE18948284698BB2"
}

Response samples

Content type
application/json
{
  • "id": "E9996334F8134DBCBE18948284698BB2"
}

Gets a 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,
  • "workPackage": "E9996334F8134DBCBE18948284698BB2",
  • "priceCategory": "E9996334F8134DBCBE18948284698BB2",
  • "priceSurcharge": "E9996334F8134DBCBE18948284698BB2"
}

Creates a 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
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 associated work package.

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 for which the time tracking record shall be created.

Responses

Request samples

Content type
application/json
{
  • "workTimeStart": 1586004000,
  • "workTimeEnd": 1586005800,
  • "billingStart": 1586003400,
  • "billingEnd": 1586006100,
  • "message": "Briefing about Octaved Flow",
  • "isJourney": false,
  • "workPackage": "E9996334F8134DBCBE18948284698BB2",
  • "priceCategory": "E9996334F8134DBCBE18948284698BB2",
  • "priceSurcharge": "E9996334F8134DBCBE18948284698BB2",
  • "user": "E9996334F8134DBCBE18948284698BB2"
}

Patches a 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
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 associated work package.

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.

Responses

Request samples

Content type
application/json
{
  • "workTimeStart": 1586004000,
  • "workTimeEnd": 1586005800,
  • "billingStart": 1586003400,
  • "billingEnd": 1586006100,
  • "message": "Briefing about Octaved Flow",
  • "isJourney": false,
  • "workPackage": "E9996334F8134DBCBE18948284698BB2",
  • "priceCategory": "E9996334F8134DBCBE18948284698BB2",
  • "priceSurcharge": "E9996334F8134DBCBE18948284698BB2"
}

Deletes a 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
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
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)
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
    projectId
    required
    string^[0-9A-F]{32}$

    The project id for this billing.

    workPackageIds
    required
    Array of strings

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

    The project id for this billing.

    workPackageIds
    required
    Array of strings

    Work packages to include in this billing. Only descendants of 'projectId' are included.

    internalComment
    string <= 5000 characters

    An internal comment, which is displayed in the UI.

    publicNote
    string <= 5000 characters

    A public note rendered in the PDF exports.

    EnumFlowBillingInterval (string) or null

    The interval for billing in period.

    date (string) or null

    The interval's from date for billing in period.

    date (string) or null

    The interval's inclusive end date for billing in period. E.g. for a month, this should be the last day of that month.

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    {
    • "id": "E9996334F8134DBCBE18948284698BB2"
    }

    Patch billing

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

    UUID of the billing

    Request Body schema: application/json
    internalComment
    string <= 5000 characters

    An internal comment, which is displayed in the UI.

    publicNote
    string <= 5000 characters

    A public note rendered in the PDF exports.

    erpStatus
    string
    Default: "none"
    Enum: "none" "transmittedFailed" "transmittedSuccessful" "processing" "processedWithWarning" "processedWithError" "processedSuccessful"

    The transmitted* status are set by Octaved upon webhook transmission. Setting this status to any process* is optional, it will be displayed in the UI.

    erpReference
    string <= 191 characters

    An optional reference value like an id on the erp side.

    erpMessage
    string

    An optional result message for e.g. warnings or error messages displayed in the UI.

    Responses

    Request samples

    Content type
    application/json
    {
    • "internalComment": "string",
    • "publicNote": "string",
    • "erpStatus": "none",
    • "erpReference": "string",
    • "erpMessage": "string"
    }

    Delete billing

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

    UUID of the billing

    Responses

    Simple search

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

    path Parameters
    ident
    required
    string

    See request body schema properties for the available idents.

    value
    string

    See request body schema for the appropriate type.

    Request Body schema: Supported search idents and their values
    createdInDateRange
    string (dateRange) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}-20[0-9]{2}-[0-9...
    customerId
    string (uuid) ^[0-9A-F]{32}$
    erpReference
    string (varchar191) <= 191 characters
    erpStatus
    string (EnumFlowBillingErpStatus)
    Enum: "none" "transmittedFailed" "transmittedSuccessful" "processing" "processedWithWarning" "processedWithError" "processedSuccessful"
    projectId
    string (uuid) ^[0-9A-F]{32}$
    timeTrackingRecordId
    string (uuid) ^[0-9A-F]{32}$
    workPackageId
    string (uuid) ^[0-9A-F]{32}$

    Responses

    Response samples

    Content type
    application/json
    [
    • "E9996334F8134DBCBE18948284698BB2"
    ]

    Complex search

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

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

    See the simple search request for the supported search idents.

    Request Body schema: application/json
    One of
    ident
    required
    string non-empty
    value
    string

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    [
    • "E9996334F8134DBCBE18948284698BB2"
    ]

    Billings exports

    Export routes for billings

    JSON export

    The response schema is identical to the one transmitted to the billing webhook

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

    UUID of the billing

    Responses

    Response samples

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

    CSV export

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

    UUID of the billing

    type
    required
    string
    Enum: "timeSheet" "sumsAndPrices"

    Responses

    Excel sums export

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

    UUID of the billing

    query Parameters
    object (excelSums)

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

    Responses

    Excel time sheet export

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

    UUID of the billing

    query Parameters
    object (excelTimeSheet)

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

    Responses

    PDF time sheet export

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

    UUID of the billing

    query Parameters
    object (pdfTimeSheet)

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

    Responses

    Material resource folders

    Routes for material resource folders

    Gets material resource folders by ids

    query Parameters
    ids[]
    required
    Array of strings (uuidArray)
    Example: ids[]=E9996334F8134DBCBE18948284698BB2

    UUIDs of the material resource folders

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Creates a material resource folder

    Request Body schema: application/json
    parentNodeId
    string^[0-9A-F]{32}$
    Default: "<root material resource folder id>"

    The UUID of the parent, which must be another material resource folder.

    labels
    Array of strings

    Ids of labels associated with the node.

    name
    required
    string (varchar191) <= 191 characters

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    {
    • "id": "E9996334F8134DBCBE18948284698BB2"
    }

    Gets a material resource folder

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

    UUID of the material resource folder

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "E9996334F8134DBCBE18948284698BB2",
    • "createdOn": 1580555700,
    • "lastChanged": 1580555700,
    • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
    • "nodeType": "materialResourceFolder",
    • "labels": [
      ],
    • "name": "string"
    }

    Creates a material resource folder

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

    UUID of the material resource folder

    Request Body schema: application/json
    parentNodeId
    string^[0-9A-F]{32}$
    Default: "<root material resource folder id>"

    The UUID of the parent, which must be another material resource folder.

    labels
    Array of strings

    Ids of labels associated with the node.

    name
    required
    string (varchar191) <= 191 characters

    Responses

    Request samples

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

    Patches a material resource folder

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

    UUID of the material resource folder

    Request Body schema: application/json
    labels
    Array of strings

    Ids of labels associated with the node.

    name
    string (varchar191) <= 191 characters

    Responses

    Request samples

    Content type
    application/json
    {
    • "labels": [
      ],
    • "name": "string"
    }

    Deletes a material resource folder

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

    UUID of the material resource folder

    Responses

    Simple search

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

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

    path Parameters
    ident
    required
    string
    value
    string

    The content/format depends on the search ident.

    query Parameters
    yieldObjects
    string
    Value: "1"
    Request Body schema: Supported search idents and their values
    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).

    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
    One of
    ident
    required
    string non-empty
    value
    string

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    Example
    [ ]

    Material resources

    Routes for material resources

    Gets material resources by ids

    query Parameters
    ids[]
    required
    Array of strings (uuidArray)
    Example: ids[]=E9996334F8134DBCBE18948284698BB2

    UUIDs of the material resources

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Creates a material resource

    Request Body schema: application/json
    parentNodeId
    string^[0-9A-F]{32}$
    Default: "<root material resource folder id>"

    The UUID of the parent, which must be another material resource folder.

    labels
    Array of strings

    Ids of labels associated with the node.

    name
    required
    string (varchar191) <= 191 characters
    color
    string <= 6 characters

    The color in hexadecimal notation.

    isActive
    boolean

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    {
    • "id": "E9996334F8134DBCBE18948284698BB2"
    }

    Gets a material resource

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

    UUID of the material resource

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "E9996334F8134DBCBE18948284698BB2",
    • "createdOn": 1580555700,
    • "lastChanged": 1580555700,
    • "parentNodeId": "E9996334F8134DBCBE18948284698BB2",
    • "nodeType": "materialResource",
    • "labels": [
      ],
    • "name": "string",
    • "color": "7c9754",
    • "isActive": true
    }

    Creates a material resource

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

    UUID of the material resource

    Request Body schema: application/json
    parentNodeId
    string^[0-9A-F]{32}$
    Default: "<root material resource folder id>"

    The UUID of the parent, which must be another material resource folder.

    labels
    Array of strings

    Ids of labels associated with the node.

    name
    required
    string (varchar191) <= 191 characters
    color
    string <= 6 characters

    The color in hexadecimal notation.

    isActive
    boolean

    Responses

    Request samples

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

    Patches a material resource

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

    UUID of the material resource

    Request Body schema: application/json
    labels
    Array of strings

    Ids of labels associated with the node.

    name
    string (varchar191) <= 191 characters
    color
    string <= 6 characters

    The color in hexadecimal notation.

    isActive
    boolean

    Responses

    Request samples

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

    Deletes a material resource

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

    UUID of the material resource

    Responses

    Simple search

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

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

    path Parameters
    ident
    required
    string
    value
    string

    The content/format depends on the search ident.

    query Parameters
    yieldObjects
    string
    Value: "1"
    Request Body schema: Supported search idents and their values
    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).

    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
    One of
    ident
    required
    string non-empty
    value
    string

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    Example
    [ ]

    Organization users

    Routes for organization users

    Gets emails by user ids

    query Parameters
    ids[]
    required
    Array of strings (uuidArray)
    Example: ids[]=E9996334F8134DBCBE18948284698BB2

    UUIDs of the organization users

    Responses

    Response samples

    Content type
    application/json
    {
    • "E9996334F8134DBCBE18948284698BB2": "max.mustermann@domain.de"
    }

    Working time tracking

    Routes to read/write working time tracking

    Get days

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

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

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

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

    Request Body schema: application/json
    dates
    required
    Array of strings (dateArray)
    userIds
    required
    Array of strings (uuidArray)
    includeEntries
    boolean

    Optionally opt-in to receiving individual entries with all their revisions

    includeStats
    boolean

    Optionally opt-in to receiving month/week statistics

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Add entry

    Adds a single new working time entry

    Request Body schema: application/json
    startDateTime
    required
    string^20[0-9]{2}-[0-9]{2}-[0-9]{2} ([0-1][0-9]|2[0...

    The working time start, seconds are ignored

    required
    dateTime (string) or null

    The working time end, seconds are ignored. This must be on the same date as the startDateTime, unless it is exactly midnight of the next day. When editing for a different user or outside the days tolerance, the end time is also required.

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

    The user id for which this working time shall be recorded

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    {
    • "id": "E9996334F8134DBCBE18948284698BB2"
    }

    Get entry

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

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

    The id of the entry

    Responses

    Response samples

    Content type
    application/json
    {
    • "id": "E9996334F8134DBCBE18948284698BB2",
    • "revisions": [
      ],
    • "userId": "E9996334F8134DBCBE18948284698BB2"
    }

    Add/update entry

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

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

    The id of the entry

    Request Body schema: application/json
    startDateTime
    required
    string^20[0-9]{2}-[0-9]{2}-[0-9]{2} ([0-1][0-9]|2[0...

    The working time start, seconds are ignored

    required
    dateTime (string) or null

    The working time end, seconds are ignored. This must be on the same date as the startDateTime, unless it is exactly midnight of the next day. When editing for a different user or outside the days tolerance, the end time is also required.

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

    The user id for which this working time shall be recorded

    Responses

    Request samples

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

    Response samples

    Content type
    application/json
    {
    • "id": "E9996334F8134DBCBE18948284698BB2"
    }

    Delete entry

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

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

    The id of the entry

    Responses

    Add/update entries

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

    Request Body schema: application/json
    required
    Array of objects

    Responses

    Request samples

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

    Response samples

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

    Work time/off-days

    Routes to define work times and off-days

    Get definitions

    Gets the work time definitions for the given user/user group ids. Each result also includes all inherited definitions. Definitions "closer" to the user take precedence.

    Note that some response properties here are not marked as "required". These properties are omitted if the API user lacks sufficient permissions to read the data. See Settings > Permissions > Work times/off-days.

    query Parameters
    ids[]
    required
    Array of strings (uuidArray)
    Example: ids[]=E9996334F8134DBCBE18948284698BB2

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

    Responses

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Get work hours Deprecated

    Deprecated - use "Get work minutes" for better precision

    path Parameters
    from
    required
    string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
    Example: 2020-03-23

    The start date for the date range to load

    to
    required
    string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
    Example: 2020-03-23

    The end date for the date range to

    query Parameters
    ids[]
    required
    Array of strings (uuidArray)
    Example: ids[]=E9996334F8134DBCBE18948284698BB2

    UUIDs of the users to load the work hours for

    Responses

    Response samples

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

    Get work minutes

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

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

    path Parameters
    from
    required
    string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
    Example: 2020-03-23

    The start date for the date range to load

    to
    required
    string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
    Example: 2020-03-23

    The end date for the date range to

    query Parameters
    ids[]
    required
    Array of strings (uuidArray)
    Example: ids[]=E9996334F8134DBCBE18948284698BB2

    UUIDs of the users to load the work minutes for

    Responses

    Response samples

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

    Group standard work hours Deprecated

    Deprecated - use "Group standard work minutes" for better precision

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

    The id of the user group

    Request Body schema: application/json
    ^(1|2|3|4|5|6|7)$
    pattern property
    number [ 0 .. 24 ]

    Record of weekdays to work hours. If you omit a weekday, any definition is removed and the hours fall back to the next inherited level or system default.

    Responses

    Request samples

    Content type
    application/json
    {
    • "2": 7.5,
    • "5": 4
    }

    Group standard work minutes

    Updates the standard work minutes for a user group. Leaving out a weekday in the request record will remove the definition.

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

    The id of the user group

    Request Body schema: application/json
    ^(1|2|3|4|5|6|7)$
    pattern property
    integer [ 0 .. 1440 ]

    Record of weekdays to work minutes. If you omit a weekday, any definition is removed and the minutes fall back to the next inherited level or system default.

    Responses

    Request samples

    Content type
    application/json
    {
    • "2": 450,
    • "5": 240
    }

    User standard work hours Deprecated

    Deprecated - use "User standard work minutes" for better precision

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

    The id of the user

    Request Body schema: application/json
    ^(1|2|3|4|5|6|7)$
    pattern property
    number [ 0 .. 24 ]

    Record of weekdays to work hours. If you omit a weekday, any definition is removed and the hours fall back to the next inherited level or system default.

    Responses

    Request samples

    Content type
    application/json
    {
    • "2": 7.5,
    • "5": 4
    }

    User standard work minutes

    Updates the standard work minutes for a user. Leaving out a weekday in the request record will remove the definition.

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

    The id of the user

    Request Body schema: application/json
    ^(1|2|3|4|5|6|7)$
    pattern property
    integer [ 0 .. 1440 ]

    Record of weekdays to work minutes. If you omit a weekday, any definition is removed and the minutes fall back to the next inherited level or system default.

    Responses

    Request samples

    Content type
    application/json
    {
    • "2": 450,
    • "5": 240
    }

    Group custom work time

    Adds or updates a custom work time definition for a user group

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

    The id of the user group

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

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

    Request Body schema: application/json
    type
    required
    string (CustomWorkTimeType)
    Enum: "halfVacationDay" "nonStandardWorkTime" "offDayOther" "partialSickLeave" "sickLeave" "vacationDay"
    startDate
    required
    string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
    endDate
    required
    string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
    hours
    number [ 0 .. 24 ]
    Deprecated
    Default: 0

    Deprecated - use minutes instead of hours to avoid decimal rounding problems

    minutes
    integer [ 0 .. 1440 ]
    Default: 0

    For off-days this is 0. For partial sick leaves this should be set to the exact tracked working time of the day to have zero overtime.

    comment
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "type": "halfVacationDay",
    • "startDate": "2020-03-23",
    • "endDate": "2020-03-23",
    • "hours": 0,
    • "minutes": 0,
    • "comment": "string"
    }

    User custom work time

    Adds or updates a custom work time definition for a user

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

    The id of the user

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

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

    Request Body schema: application/json
    type
    required
    string (CustomWorkTimeType)
    Enum: "halfVacationDay" "nonStandardWorkTime" "offDayOther" "partialSickLeave" "sickLeave" "vacationDay"
    startDate
    required
    string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
    endDate
    required
    string (date) ^20[0-9]{2}-[0-9]{2}-[0-9]{2}$
    hours
    number [ 0 .. 24 ]
    Deprecated
    Default: 0

    Deprecated - use minutes instead of hours to avoid decimal rounding problems

    minutes
    integer [ 0 .. 1440 ]
    Default: 0

    For off-days this is 0. For partial sick leaves this should be set to the exact tracked working time of the day to have zero overtime.

    comment
    string

    Responses

    Request samples

    Content type
    application/json
    {
    • "type": "halfVacationDay",
    • "startDate": "2020-03-23",
    • "endDate": "2020-03-23",
    • "hours": 0,
    • "minutes": 0,
    • "comment": "string"
    }

    Delete custom work time

    Deletes a custom work time definition

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

    The id of the custom work time

    Responses