OCS Out-of-office API

Added in version 28.0.

The OCS Out-of-office API allows you to access and modify out-of-office data of users.

The base URL for all calls to the share API is: <nextcloud_base_url>/ocs/v2.php/apps/dav/api/v1/outOfOffice

All calls to OCS endpoints require the OCS-APIRequest header to be set to true.

Fetch ongoing data

Fetch data of the ongoing out-of-office period of a user.

Method: GET
Endpoint: /{userId}
Response:
- Status code:
  
  200 OK Out-of-office data
  
  404 Not Found If the user does not have an ongoing out-of-office period
- Data (is only sent if the status code is 200 OK):

field	type	Description
`id`	int	Database ID of the absence data entity
`userId`	string	ID of the user which the data belongs to
`firstDay`	string	First day of the absence in format `YYYY-MM-DD`
`lastDay`	string	Last day of the absence in format `YYYY-MM-DD`
`status`	string	Short text that is set as user status during the absence
`message`	string	Longer multiline message that is shown to others during the absence
`replacementUserId`	string/null	ID of the replacement user
`replacementUserDisplayName`	string/null	Displayname of the replacement user

Fetch upcoming or ongoing data

The returned out-of-office period might not have started yet. This endpoint will return data of the ongoing or next upcoming out-of-office period of a user.

Method: GET
Endpoint: /{userId}
Response:
- Status code:
  
  200 OK Out-of-office data
  
  404 Not Found If the user did not schedule an out-of-office period
- Data (is only sent if the status code is 200 OK):

field	type	Description
`id`	int	Database ID of the absence data entity
`userId`	string	ID of the user which the data belongs to
`firstDay`	string	First day of the absence in format `YYYY-MM-DD`
`lastDay`	string	Last day of the absence in format `YYYY-MM-DD`
`status`	string	Short text that is set as user status during the absence
`message`	string	Longer multiline message that is shown to others during the absence
`replacementUserId`	string/null	ID of the replacement user
`replacementUserDisplayName`	string/null	Displayname of the replacement user

Modify out-of-office data

It is only possible to modify out-of-office data of the currently logged in user.

Method: POST
Endpoint: /
Data:

field	type	Description
`firstDay`	string	First day of the absence in format `YYYY-MM-DD`
`lastDay`	string	Last day of the absence in format `YYYY-MM-DD`
`status`	string	Short text that is set as user status during the absence
`message`	string	Longer multiline message that is shown to others during the absence
`replacementUserId`	string/null	ID of the replacement user
`replacementUserDisplayName`	string/null	Displayname of the replacement user

Response:
- Status code:
  
  200 OK Updated out-of-office data
  
  400 Bad Request If the first day is not before the last day
  
  404 Not Found If a replacement user ID is provided but no corresponding user is found
  
  401 Unauthorized If the user is not logged in
- Data (is only sent if the status code is 200 OK):

field	type	Description
`id`	int	Database ID of the absence data entity
`userId`	string	ID of the user which the data belongs to
`firstDay`	string	First day of the absence in format `YYYY-MM-DD`
`lastDay`	string	Last day of the absence in format `YYYY-MM-DD`
`status`	string	Short text that is set as user status during the absence
`message`	string	Longer multiline message that is shown to others during the absence
`replacementUserId`	string/null	ID of the replacement user
`replacementUserDisplayName`	string/null	Displayname of the replacement user

Clear data and disable out-of-office

It is only possible to clear out-of-office data of the currently logged in user.

Method: DELETE
Endpoint: /
Response:
- Status code:
  
  200 OK Out-of-office data was cleared
  
  401 Unauthorized If the user is not logged in