API: User Working Times

User working times allow configuring per-user working hours and personal non-working days, in addition to the system-wide work schedule.

A UserWorkingHours record defines how many hours a user works on each day of the week, along with an availability factor, effective from a given date (validFrom). Multiple records can exist for a user, each representing a period of their working time configuration. Only the most recently effective record (i.e., the one with the latest validFrom that is not in the future) is used for capacity calculations.

A UserNonWorkingTime marks a date range as non-working for a user (e.g., a personal day off or a local holiday not covered by the system-wide non-working days). If a personal non-working time overlaps with system-wide non-working days, those days are not counted twice.

UserWorkingHours Actions

Link Description Condition
update Update this working hours record Record has not yet taken effect (validFrom is in the future); Permission: see below
delete Delete this working hours record Permission: see below

UserWorkingHours Linked Properties

Link Description Type Constraints Supported operations
self This working hours record UserWorkingHours not null READ
user The user this working hours record belongs to User not null READ

UserWorkingHours Local Properties

Property Description Type Constraints Supported operations
id The unique identifier of the record Integer x > 0 READ
validFrom The date from which this working hours configuration takes effect (ISO 8601 format) Date not null READ / WRITE
mondayHours Hours worked on Monday Float x >= 0 READ / WRITE
tuesdayHours Hours worked on Tuesday Float x >= 0 READ / WRITE
wednesdayHours Hours worked on Wednesday Float x >= 0 READ / WRITE
thursdayHours Hours worked on Thursday Float x >= 0 READ / WRITE
fridayHours Hours worked on Friday Float x >= 0 READ / WRITE
saturdayHours Hours worked on Saturday Float x >= 0 READ / WRITE
sundayHours Hours worked on Sunday Float x >= 0 READ / WRITE
availabilityFactor Percentage of working hours the user is available (0–100) Integer 0 <= x <= 100 READ / WRITE

UserWorkingHours Permissions

  • Administrators can read and manage working hours for any user.
  • Users with the global manage_own_working_times permission can read and manage their own working hours.
  • Users with the global manage_working_times permission can read and manage working hours for any user.
  • All users can read their own working hours records even without a special permission.
  • Records that have already taken effect (i.e., validFrom is today or in the past) cannot be updated.

UserNonWorkingTime Actions

Link Description Condition
delete Delete this non-working day Permission: see below

UserNonWorkingTime Linked Properties

Link Description Type Constraints Supported operations
self This non-working day UserNonWorkingTime not null READ
user The user this non-working day belongs to User not null READ

UserNonWorkingTime Local Properties

Property Description Type Constraints Supported operations
id The unique identifier of the record Integer x > 0 READ
startDate The first date of the non-working time range (ISO 8601 format) Date not null READ / WRITE
endDate The last date of the non-working time range (ISO 8601 format) Date not null, >= startDate READ / WRITE

UserNonWorkingTime Permissions

  • Administrators can read and manage personal non-working days for any user.
  • Users with the global manage_own_working_times permission can read and manage their own non-working days.
  • Users with the global manage_working_times permission can read and manage non-working days for any user.
  • A personal non-working time must not overlap with another non-working time record for the same user.

Methods

List personal non-working times for a user

Returns all personal non-working times for the given user, ordered by start date ascending.

Personal non-working times mark date ranges as non-working for a user (e.g., a local holiday or personal day off not covered by the system-wide non-working days).

Required permissions:

  • Administrators can view non-working days for any user.
  • Users with the global manage_own_working_times permission can view their own records.
  • Users with the global manage_working_times permission can view non-working days for any user.

Use me as the id to reference the current user.

id
string

required path

User id. Use me to reference the current user.

Example:
42

year
integer

optional query

Filter results to the given year. Defaults to the current year if not provided.

Example:
2025

200

OK

UserNonWorkingTimeCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "This collection of non-working times records.\n**Resource**: UserNonWorkingTimeCollectionModel"
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "description": "The array of personal non-working times for the user, ordered by start date ascending.",
              "items": {
                "$ref": "#/components/schemas/UserNonWorkingTimeModel"
              }
            }
          }
        }
      }
    }
  ],
  "example": {
    "_type": "Collection",
    "total": 2,
    "count": 2,
    "_links": {
      "self": {
        "href": "/api/v3/users/42/non_working_times"
      }
    },
    "_embedded": {
      "elements": [
        {
          "_type": "UserNonWorkingTime",
          "id": 7,
          "startDate": "2025-06-16",
          "endDate": "2025-06-20",
          "_links": {
            "self": {
              "href": "/api/v3/users/42/non_working_times/7"
            },
            "user": {
              "href": "/api/v3/users/42",
              "title": "Jane Doe"
            }
          }
        },
        {
          "_type": "UserNonWorkingTime",
          "id": 8,
          "startDate": "2025-12-24",
          "endDate": "2025-12-24",
          "_links": {
            "self": {
              "href": "/api/v3/users/42/non_working_times/8"
            },
            "user": {
              "href": "/api/v3/users/42",
              "title": "Jane Doe"
            }
          }
        }
      ]
    }
  }
}

401

Returned if the client is not authenticated.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
  "message": "You need to be authenticated to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the user does not exist or is not visible to the requesting user.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified user does not exist or you do not have permission to view them."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Create a personal non-working day for a user

Creates a personal non-working time range for the given user.

The date range must not overlap with an existing non-working time record for the same user.

Required permissions:

  • Administrators can create non-working days for any user.
  • Users with the global manage_own_working_times permission can create records for themselves.
  • Users with the global manage_working_times permission can create non-working days for any user.

Use me as the id to reference the current user.

id
string

required path

User id. Use me to reference the current user.

Example:
42

{
  "startDate": "2025-06-16",
  "endDate": "2025-06-20"
}

{
  "_type": {
    "type": "string",
    "enum": [
      "UserNonWorkingTime"
    ]
  },
  "id": {
    "type": "integer",
    "description": "The unique identifier of the non-working time record.",
    "minimum": 1
  },
  "startDate": {
    "type": "string",
    "format": "date",
    "description": "The first date of the non-working time range in ISO 8601 format (YYYY-MM-DD)."
  },
  "endDate": {
    "type": "string",
    "format": "date",
    "description": "The last date of the non-working time range in ISO 8601 format (YYYY-MM-DD).\nMust be greater than or equal to `startDate`."
  },
  "_links": {
    "type": "object",
    "required": [
      "self",
      "user"
    ],
    "properties": {
      "self": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "This non-working time record.\n**Resource**: UserNonWorkingTime"
          }
        ]
      },
      "user": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The user this non-working time belongs to.\n**Resource**: User"
          }
        ]
      }
    }
  }
}

201

Created

UserNonWorkingTimeModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "startDate",
    "endDate"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "UserNonWorkingTime"
      ]
    },
    "id": {
      "type": "integer",
      "description": "The unique identifier of the non-working time record.",
      "minimum": 1
    },
    "startDate": {
      "type": "string",
      "format": "date",
      "description": "The first date of the non-working time range in ISO 8601 format (YYYY-MM-DD)."
    },
    "endDate": {
      "type": "string",
      "format": "date",
      "description": "The last date of the non-working time range in ISO 8601 format (YYYY-MM-DD).\nMust be greater than or equal to `startDate`."
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "user"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This non-working time record.\n**Resource**: UserNonWorkingTime"
            }
          ]
        },
        "user": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user this non-working time belongs to.\n**Resource**: User"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "UserNonWorkingTime",
    "id": 7,
    "startDate": "2025-06-16",
    "endDate": "2025-06-20",
    "_links": {
      "self": {
        "href": "/api/v3/users/42/non_working_times/7"
      },
      "user": {
        "href": "/api/v3/users/42",
        "title": "Jane Doe"
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

401

Returned if the client is not authenticated.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
  "message": "You need to be authenticated to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: manage_working_times globally (for other users) or manage_own_working_times globally (for own records).

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the user does not exist or is not visible to the requesting user.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified user does not exist or you do not have permission to view them."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if the request body contains invalid parameters, or if the date range overlaps with an existing non-working time record for the user.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Validation failed."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

View a personal non-working time record

Returns a single personal non-working time record for the given user.

Required permissions:

  • Administrators can view non-working time records for any user.
  • Users with the global manage_own_working_times permission can view their own records.
  • Users with the global manage_working_times permission can view non-working time records for any user.

Use me as the id to reference the current user.

id
string

required path

User id. Use me to reference the current user.

Example:
42

non_working_time_id
integer

required path

The id of the personal non-working time record.

Example:
7

200

OK

UserNonWorkingTimeModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "startDate",
    "endDate"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "UserNonWorkingTime"
      ]
    },
    "id": {
      "type": "integer",
      "description": "The unique identifier of the non-working time record.",
      "minimum": 1
    },
    "startDate": {
      "type": "string",
      "format": "date",
      "description": "The first date of the non-working time range in ISO 8601 format (YYYY-MM-DD)."
    },
    "endDate": {
      "type": "string",
      "format": "date",
      "description": "The last date of the non-working time range in ISO 8601 format (YYYY-MM-DD).\nMust be greater than or equal to `startDate`."
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "user"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This non-working time record.\n**Resource**: UserNonWorkingTime"
            }
          ]
        },
        "user": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user this non-working time belongs to.\n**Resource**: User"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "UserNonWorkingTime",
    "id": 7,
    "startDate": "2025-06-16",
    "endDate": "2025-06-20",
    "_links": {
      "self": {
        "href": "/api/v3/users/42/non_working_times/7"
      },
      "user": {
        "href": "/api/v3/users/42",
        "title": "Jane Doe"
      }
    }
  }
}

401

Returned if the client is not authenticated.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
  "message": "You need to be authenticated to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the user or non-working time record does not exist, or if the requesting user does not have permission to view it.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Update a personal non-working time record

Updates the given personal non-working time record.

Required permissions:

  • Administrators can update non-working time records for any user.
  • Users with the global manage_own_working_times permission can update their own records.
  • Users with the global manage_working_times permission can update non-working time records for any user.

Use me as the id to reference the current user.

id
string

required path

User id. Use me to reference the current user.

Example:
42

non_working_time_id
integer

required path

The id of the personal non-working time record.

Example:
7

{
  "startDate": "2025-06-23",
  "endDate": "2025-06-27"
}

{
  "_type": {
    "type": "string",
    "enum": [
      "UserNonWorkingTime"
    ]
  },
  "id": {
    "type": "integer",
    "description": "The unique identifier of the non-working time record.",
    "minimum": 1
  },
  "startDate": {
    "type": "string",
    "format": "date",
    "description": "The first date of the non-working time range in ISO 8601 format (YYYY-MM-DD)."
  },
  "endDate": {
    "type": "string",
    "format": "date",
    "description": "The last date of the non-working time range in ISO 8601 format (YYYY-MM-DD).\nMust be greater than or equal to `startDate`."
  },
  "_links": {
    "type": "object",
    "required": [
      "self",
      "user"
    ],
    "properties": {
      "self": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "This non-working time record.\n**Resource**: UserNonWorkingTime"
          }
        ]
      },
      "user": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The user this non-working time belongs to.\n**Resource**: User"
          }
        ]
      }
    }
  }
}

200

OK

UserNonWorkingTimeModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "startDate",
    "endDate"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "UserNonWorkingTime"
      ]
    },
    "id": {
      "type": "integer",
      "description": "The unique identifier of the non-working time record.",
      "minimum": 1
    },
    "startDate": {
      "type": "string",
      "format": "date",
      "description": "The first date of the non-working time range in ISO 8601 format (YYYY-MM-DD)."
    },
    "endDate": {
      "type": "string",
      "format": "date",
      "description": "The last date of the non-working time range in ISO 8601 format (YYYY-MM-DD).\nMust be greater than or equal to `startDate`."
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "user"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This non-working time record.\n**Resource**: UserNonWorkingTime"
            }
          ]
        },
        "user": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user this non-working time belongs to.\n**Resource**: User"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "UserNonWorkingTime",
    "id": 7,
    "startDate": "2025-06-16",
    "endDate": "2025-06-20",
    "_links": {
      "self": {
        "href": "/api/v3/users/42/non_working_times/7"
      },
      "user": {
        "href": "/api/v3/users/42",
        "title": "Jane Doe"
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

401

Returned if the client is not authenticated.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
  "message": "You need to be authenticated to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: manage_working_times globally (for other users) or manage_own_working_times globally (for own records).

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the user or non-working time record does not exist, or if the requesting user does not have permission to view it.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if the request body contains invalid parameters, or if the date range overlaps with an existing non-working time record for the user.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Validation failed."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Delete a personal non-working time record

Removes the personal non-working time record for the given user.

Required permissions:

  • Administrators can delete non-working time records for any user.
  • Users with the global manage_own_working_times permission can delete their own records.
  • Users with the global manage_working_times permission can delete non-working time records for any user.

Use me as the id to reference the current user.

id
string

required path

User id. Use me to reference the current user.

Example:
42

non_working_time_id
integer

required path

The id of the personal non-working time record.

Example:
7

204

No Content. The record was deleted successfully.

401

Returned if the client is not authenticated.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
  "message": "You need to be authenticated to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: manage_working_times globally (for other users) or manage_own_working_times globally (for own records).

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the user or non-working time record does not exist, or if the requesting user does not have permission to view it.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

List working hours for a user

Returns all working hours records for the given user, ordered by validFrom descending.

Multiple records may exist for a user; each represents a period of their working time configuration. The most recently effective record (the one with the latest validFrom that is not in the future) is used for capacity calculations.

Required permissions:

  • Administrators can view working hours for any user.
  • Users with the global manage_working_times permission can view working hours for any user.
  • Any user can view their own working hours records.

Use me as the id to reference the current user.

id
string

required path

User id. Use me to reference the current user.

Example:
42

200

OK

UserWorkingHoursCollectionModel
{
  "allOf": [
    {
      "$ref": "#/components/schemas/CollectionModel"
    },
    {
      "type": "object",
      "required": [
        "_links",
        "_embedded"
      ],
      "properties": {
        "_links": {
          "type": "object",
          "required": [
            "self"
          ],
          "properties": {
            "self": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Link"
                },
                {
                  "description": "This collection of working hours records.\n**Resource**: UserWorkingHoursCollectionModel"
                }
              ]
            }
          }
        },
        "_embedded": {
          "type": "object",
          "required": [
            "elements"
          ],
          "properties": {
            "elements": {
              "type": "array",
              "description": "The array of working hours records for the user, ordered by `validFrom` descending.",
              "items": {
                "$ref": "#/components/schemas/UserWorkingHoursModel"
              }
            }
          }
        }
      }
    }
  ],
  "example": {
    "_type": "Collection",
    "total": 2,
    "count": 2,
    "_links": {
      "self": {
        "href": "/api/v3/users/42/working_hours"
      }
    },
    "_embedded": {
      "elements": [
        {
          "_type": "UserWorkingHours",
          "id": 2,
          "validFrom": "2025-01-01",
          "mondayHours": 6.0,
          "tuesdayHours": 6.0,
          "wednesdayHours": 6.0,
          "thursdayHours": 6.0,
          "fridayHours": 6.0,
          "saturdayHours": 0.0,
          "sundayHours": 0.0,
          "availabilityFactor": 80,
          "_links": {
            "self": {
              "href": "/api/v3/users/42/working_hours/2"
            },
            "user": {
              "href": "/api/v3/users/42",
              "title": "Jane Doe"
            }
          }
        },
        {
          "_type": "UserWorkingHours",
          "id": 1,
          "validFrom": "2024-01-01",
          "mondayHours": 8.0,
          "tuesdayHours": 8.0,
          "wednesdayHours": 8.0,
          "thursdayHours": 8.0,
          "fridayHours": 8.0,
          "saturdayHours": 0.0,
          "sundayHours": 0.0,
          "availabilityFactor": 100,
          "_links": {
            "self": {
              "href": "/api/v3/users/42/working_hours/1"
            },
            "user": {
              "href": "/api/v3/users/42",
              "title": "Jane Doe"
            }
          }
        }
      ]
    }
  }
}

401

Returned if the client is not authenticated.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
  "message": "You need to be authenticated to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the user does not exist or is not visible to the requesting user.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified user does not exist or you do not have permission to view them."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Create a working hours record for a user

Creates a new working hours record for the given user, effective from the given date.

Required permissions:

  • Administrators can create working hours records for any user.
  • Users with the global manage_own_working_times permission can create records for themselves.
  • Users with the global manage_working_times permission can create working hours records for any user.

Use me as the id to reference the current user.

id
string

required path

User id. Use me to reference the current user.

Example:
42

{
  "validFrom": "2025-01-01",
  "mondayHours": 8,
  "tuesdayHours": 8,
  "wednesdayHours": 8,
  "thursdayHours": 8,
  "fridayHours": 8,
  "saturdayHours": 0,
  "sundayHours": 0,
  "availabilityFactor": 100
}

{
  "_type": {
    "type": "string",
    "enum": [
      "UserWorkingHours"
    ]
  },
  "id": {
    "type": "integer",
    "description": "The unique identifier of the working hours record.",
    "minimum": 1
  },
  "validFrom": {
    "type": "string",
    "format": "date",
    "description": "The date from which this working hours configuration is in effect (ISO 8601 format).\nMultiple records may exist for a user; the one with the latest `validFrom` that is\nnot in the future is the currently active record."
  },
  "mondayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Monday.",
    "minimum": 0
  },
  "tuesdayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Tuesday.",
    "minimum": 0
  },
  "wednesdayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Wednesday.",
    "minimum": 0
  },
  "thursdayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Thursday.",
    "minimum": 0
  },
  "fridayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Friday.",
    "minimum": 0
  },
  "saturdayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Saturday.",
    "minimum": 0
  },
  "sundayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Sunday.",
    "minimum": 0
  },
  "availabilityFactor": {
    "type": "integer",
    "description": "The percentage of working hours the user is available. Must be between 0 and 100.",
    "minimum": 0,
    "maximum": 100
  },
  "_links": {
    "type": "object",
    "required": [
      "self",
      "user"
    ],
    "properties": {
      "self": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "This working hours record.\n**Resource**: UserWorkingHours"
          }
        ]
      },
      "user": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The user this working hours record belongs to.\n**Resource**: User"
          }
        ]
      }
    }
  }
}

201

Created

UserWorkingHoursModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "validFrom",
    "mondayHours",
    "tuesdayHours",
    "wednesdayHours",
    "thursdayHours",
    "fridayHours",
    "saturdayHours",
    "sundayHours",
    "availabilityFactor"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "UserWorkingHours"
      ]
    },
    "id": {
      "type": "integer",
      "description": "The unique identifier of the working hours record.",
      "minimum": 1
    },
    "validFrom": {
      "type": "string",
      "format": "date",
      "description": "The date from which this working hours configuration is in effect (ISO 8601 format).\nMultiple records may exist for a user; the one with the latest `validFrom` that is\nnot in the future is the currently active record."
    },
    "mondayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Monday.",
      "minimum": 0
    },
    "tuesdayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Tuesday.",
      "minimum": 0
    },
    "wednesdayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Wednesday.",
      "minimum": 0
    },
    "thursdayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Thursday.",
      "minimum": 0
    },
    "fridayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Friday.",
      "minimum": 0
    },
    "saturdayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Saturday.",
      "minimum": 0
    },
    "sundayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Sunday.",
      "minimum": 0
    },
    "availabilityFactor": {
      "type": "integer",
      "description": "The percentage of working hours the user is available. Must be between 0 and 100.",
      "minimum": 0,
      "maximum": 100
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "user"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This working hours record.\n**Resource**: UserWorkingHours"
            }
          ]
        },
        "user": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user this working hours record belongs to.\n**Resource**: User"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "UserWorkingHours",
    "id": 1,
    "validFrom": "2024-01-01",
    "mondayHours": 8.0,
    "tuesdayHours": 8.0,
    "wednesdayHours": 8.0,
    "thursdayHours": 8.0,
    "fridayHours": 8.0,
    "saturdayHours": 0.0,
    "sundayHours": 0.0,
    "availabilityFactor": 100,
    "_links": {
      "self": {
        "href": "/api/v3/users/42/working_hours/1"
      },
      "user": {
        "href": "/api/v3/users/42",
        "title": "Jane Doe"
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

401

Returned if the client is not authenticated.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
  "message": "You need to be authenticated to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: manage_working_times globally (for other users) or manage_own_working_times globally (for own records).

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the user does not exist or is not visible to the requesting user.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The specified user does not exist or you do not have permission to view them."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if the request body contains invalid parameters.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Validation failed."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

View a working hours record

Returns a single working hours record for the given user.

Required permissions:

  • Administrators can view working hours records for any user.
  • Users with the global manage_working_times permission can view working hours for any user.
  • Any user can view their own working hours records.

id
integer

required path

User id.

Example:
42

working_hours_id
integer

required path

Working hours record id.

Example:
1

200

OK

UserWorkingHoursModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "validFrom",
    "mondayHours",
    "tuesdayHours",
    "wednesdayHours",
    "thursdayHours",
    "fridayHours",
    "saturdayHours",
    "sundayHours",
    "availabilityFactor"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "UserWorkingHours"
      ]
    },
    "id": {
      "type": "integer",
      "description": "The unique identifier of the working hours record.",
      "minimum": 1
    },
    "validFrom": {
      "type": "string",
      "format": "date",
      "description": "The date from which this working hours configuration is in effect (ISO 8601 format).\nMultiple records may exist for a user; the one with the latest `validFrom` that is\nnot in the future is the currently active record."
    },
    "mondayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Monday.",
      "minimum": 0
    },
    "tuesdayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Tuesday.",
      "minimum": 0
    },
    "wednesdayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Wednesday.",
      "minimum": 0
    },
    "thursdayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Thursday.",
      "minimum": 0
    },
    "fridayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Friday.",
      "minimum": 0
    },
    "saturdayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Saturday.",
      "minimum": 0
    },
    "sundayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Sunday.",
      "minimum": 0
    },
    "availabilityFactor": {
      "type": "integer",
      "description": "The percentage of working hours the user is available. Must be between 0 and 100.",
      "minimum": 0,
      "maximum": 100
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "user"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This working hours record.\n**Resource**: UserWorkingHours"
            }
          ]
        },
        "user": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user this working hours record belongs to.\n**Resource**: User"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "UserWorkingHours",
    "id": 1,
    "validFrom": "2024-01-01",
    "mondayHours": 8.0,
    "tuesdayHours": 8.0,
    "wednesdayHours": 8.0,
    "thursdayHours": 8.0,
    "fridayHours": 8.0,
    "saturdayHours": 0.0,
    "sundayHours": 0.0,
    "availabilityFactor": 100,
    "_links": {
      "self": {
        "href": "/api/v3/users/42/working_hours/1"
      },
      "user": {
        "href": "/api/v3/users/42",
        "title": "Jane Doe"
      }
    }
  }
}

401

Returned if the client is not authenticated.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
  "message": "You need to be authenticated to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the user or working hours record does not exist, or if the requesting user does not have permission to view it.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Update a working hours record

Updates the given working hours record.

Only records that have not yet taken effect (i.e., validFrom is in the future) can be updated. Attempting to update a record that is already in effect will return a 422 error.

Required permissions:

  • Administrators can update working hours records for any user.
  • Users with the global manage_own_working_times permission can update their own records.
  • Users with the global manage_working_times permission can update working hours for any user.

id
integer

required path

User id.

Example:
42

working_hours_id
integer

required path

Working hours record id.

Example:
2

{
  "mondayHours": 6,
  "tuesdayHours": 6,
  "wednesdayHours": 6,
  "thursdayHours": 6,
  "fridayHours": 6,
  "saturdayHours": 0,
  "sundayHours": 0,
  "availabilityFactor": 80
}

{
  "_type": {
    "type": "string",
    "enum": [
      "UserWorkingHours"
    ]
  },
  "id": {
    "type": "integer",
    "description": "The unique identifier of the working hours record.",
    "minimum": 1
  },
  "validFrom": {
    "type": "string",
    "format": "date",
    "description": "The date from which this working hours configuration is in effect (ISO 8601 format).\nMultiple records may exist for a user; the one with the latest `validFrom` that is\nnot in the future is the currently active record."
  },
  "mondayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Monday.",
    "minimum": 0
  },
  "tuesdayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Tuesday.",
    "minimum": 0
  },
  "wednesdayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Wednesday.",
    "minimum": 0
  },
  "thursdayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Thursday.",
    "minimum": 0
  },
  "fridayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Friday.",
    "minimum": 0
  },
  "saturdayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Saturday.",
    "minimum": 0
  },
  "sundayHours": {
    "type": "number",
    "format": "float",
    "description": "Hours worked on Sunday.",
    "minimum": 0
  },
  "availabilityFactor": {
    "type": "integer",
    "description": "The percentage of working hours the user is available. Must be between 0 and 100.",
    "minimum": 0,
    "maximum": 100
  },
  "_links": {
    "type": "object",
    "required": [
      "self",
      "user"
    ],
    "properties": {
      "self": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "This working hours record.\n**Resource**: UserWorkingHours"
          }
        ]
      },
      "user": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Link"
          },
          {
            "description": "The user this working hours record belongs to.\n**Resource**: User"
          }
        ]
      }
    }
  }
}

200

OK

UserWorkingHoursModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "validFrom",
    "mondayHours",
    "tuesdayHours",
    "wednesdayHours",
    "thursdayHours",
    "fridayHours",
    "saturdayHours",
    "sundayHours",
    "availabilityFactor"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "UserWorkingHours"
      ]
    },
    "id": {
      "type": "integer",
      "description": "The unique identifier of the working hours record.",
      "minimum": 1
    },
    "validFrom": {
      "type": "string",
      "format": "date",
      "description": "The date from which this working hours configuration is in effect (ISO 8601 format).\nMultiple records may exist for a user; the one with the latest `validFrom` that is\nnot in the future is the currently active record."
    },
    "mondayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Monday.",
      "minimum": 0
    },
    "tuesdayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Tuesday.",
      "minimum": 0
    },
    "wednesdayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Wednesday.",
      "minimum": 0
    },
    "thursdayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Thursday.",
      "minimum": 0
    },
    "fridayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Friday.",
      "minimum": 0
    },
    "saturdayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Saturday.",
      "minimum": 0
    },
    "sundayHours": {
      "type": "number",
      "format": "float",
      "description": "Hours worked on Sunday.",
      "minimum": 0
    },
    "availabilityFactor": {
      "type": "integer",
      "description": "The percentage of working hours the user is available. Must be between 0 and 100.",
      "minimum": 0,
      "maximum": 100
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "user"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This working hours record.\n**Resource**: UserWorkingHours"
            }
          ]
        },
        "user": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The user this working hours record belongs to.\n**Resource**: User"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "UserWorkingHours",
    "id": 1,
    "validFrom": "2024-01-01",
    "mondayHours": 8.0,
    "tuesdayHours": 8.0,
    "wednesdayHours": 8.0,
    "thursdayHours": 8.0,
    "fridayHours": 8.0,
    "saturdayHours": 0.0,
    "sundayHours": 0.0,
    "availabilityFactor": 100,
    "_links": {
      "self": {
        "href": "/api/v3/users/42/working_hours/1"
      },
      "user": {
        "href": "/api/v3/users/42",
        "title": "Jane Doe"
      }
    }
  }
}

400

Occurs when the client did not send a valid JSON object in the request body.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:InvalidRequestBody",
  "message": "The request body was not a single JSON object."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

401

Returned if the client is not authenticated.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
  "message": "You need to be authenticated to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: manage_working_times globally (for other users) or manage_own_working_times globally (for own records).

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the user or working hours record does not exist, or if the requesting user does not have permission to view it.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

406

Occurs when the client did not send a Content-Type header

"Missing content-type header"

{
  "type": "string"
}

415

Occurs when the client sends an unsupported Content-Type header.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:TypeNotSupported",
  "message": "Expected CONTENT-TYPE to be (expected value) but got (actual value)."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

422

Returned if the request body contains invalid parameters, or if the record has already taken effect and cannot be modified.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation",
  "message": "Validation failed."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

Delete a working hours record

Deletes the given working hours record.

Required permissions:

  • Administrators can delete working hours records for any user.
  • Users with the global manage_own_working_times permission can delete their own records.
  • Users with the global manage_working_times permission can delete working hours records for any user.

id
integer

required path

User id.

Example:
42

working_hours_id
integer

required path

Working hours record id.

Example:
2

204

No Content. The record was deleted successfully.

401

Returned if the client is not authenticated.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:Unauthenticated",
  "message": "You need to be authenticated to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

403

Returned if the client does not have sufficient permissions.

Required permission: manage_working_times globally (for other users) or manage_own_working_times globally (for own records).

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:MissingPermission",
  "message": "You are not authorized to access this resource."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}

404

Returned if the user or working hours record does not exist, or if the requesting user does not have permission to view it.

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}