diff --git a/README.md b/README.md index 5bc1cbb..90f9ce8 100644 --- a/README.md +++ b/README.md @@ -305,6 +305,7 @@ API endpoints - [Message Boards](https://github.com/basecamp/bc3-api/blob/master/sections/message_boards.md#message-boards) - [Message Types](https://github.com/basecamp/bc3-api/blob/master/sections/message_types.md#message-types) - [Messages](https://github.com/basecamp/bc3-api/blob/master/sections/messages.md#messages) +- [Out of office](https://github.com/basecamp/bc3-api/blob/master/sections/out_of_office.md#out-of-office) - [People](https://github.com/basecamp/bc3-api/blob/master/sections/people.md#people) - [Projects](https://github.com/basecamp/bc3-api/blob/master/sections/projects.md#projects) - [Question answers](https://github.com/basecamp/bc3-api/blob/master/sections/question_answers.md#question-answers) diff --git a/sections/out_of_office.md b/sections/out_of_office.md new file mode 100644 index 0000000..36adcff --- /dev/null +++ b/sections/out_of_office.md @@ -0,0 +1,104 @@ +Out of office +============= + +Endpoints: + +- [Get out of office](#get-out-of-office) +- [Enable out of office](#enable-out-of-office) +- [Disable out of office](#disable-out-of-office) + + +Get out of office +----------------- + +* `GET /people/2/out_of_office.json` will return the out of office status for the person with the given ID. + +When out of office is not enabled, `start_date` and `end_date` will be `null`. + +###### Example JSON Response + +```json +{ + "person": { + "id": 1049715914, + "name": "David Heinemeier Hansson" + }, + "enabled": true, + "ongoing": true, + "start_date": "2026-03-10", + "end_date": "2026-03-17" +} +``` + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/people/2/out_of_office.json +``` + + +Enable out of office +-------------------- + +* `PUT /people/2/out_of_office.json` will enable or update out of office for the person with the given ID. + +Admins on accounts with a Pro Pack can enable out of office on behalf of other people. Otherwise, you can only manage your own out of office. + +This endpoint will return `200 OK` with the current JSON representation of the out of office if the update was a success. + +**Required parameters**: + +* `start_date` - the start date in ISO 8601 format (e.g. `2026-03-10`). +* `end_date` - the end date in ISO 8601 format (e.g. `2026-03-17`). + +###### Example JSON Request + +```json +{ + "out_of_office": { + "start_date": "2026-03-10", + "end_date": "2026-03-17" + } +} +``` + +###### Example JSON Response + +```json +{ + "person": { + "id": 1049715914, + "name": "David Heinemeier Hansson" + }, + "enabled": true, + "ongoing": true, + "start_date": "2026-03-10", + "end_date": "2026-03-17" +} +``` + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json" \ + -d '{"out_of_office": {"start_date": "2026-03-10", "end_date": "2026-03-17"}}' -X PUT \ + https://3.basecampapi.com/$ACCOUNT_ID/people/2/out_of_office.json +``` + + +Disable out of office +--------------------- + +* `DELETE /people/2/out_of_office.json` will disable out of office for the person with the given ID. + +Admins on accounts with a Pro Pack can disable out of office on behalf of other people. Otherwise, you can only manage your own out of office. + +This endpoint will return `204 No Content` if the disable was a success. Disabling when out of office is already off will also return `204 No Content`. + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE \ + https://3.basecampapi.com/$ACCOUNT_ID/people/2/out_of_office.json +``` + diff --git a/sections/people.md b/sections/people.md index 82a116d..65151fe 100644 --- a/sections/people.md +++ b/sections/people.md @@ -219,6 +219,8 @@ Get person * `GET /people/2.json` will return the profile for the user with the given ID. +When a person has [out of office][3] enabled, the response will include an `out_of_office` object with `start_date` and `end_date` in ISO 8601 format (`YYYY-MM-DD`). + ###### Example JSON Response ```json @@ -266,3 +268,5 @@ See the [Get person](#get-person) endpoint for an example of the JSON response. ```shell curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/my/profile.json ``` + +[3]: https://github.com/basecamp/bc3-api/blob/master/sections/out_of_office.md#out-of-office