From 00ed665f44406ae25d23a848c08cc94129d933a2 Mon Sep 17 00:00:00 2001 From: Rob Zolkos Date: Thu, 12 Mar 2026 09:56:12 -0400 Subject: [PATCH 1/2] Document out of office API endpoints Add new out_of_office.md section with GET, PUT, DELETE endpoints nested under people. Note ISO 8601 date format in person JSON response. Update README endpoint index. --- README.md | 1 + sections/out_of_office.md | 105 ++++++++++++++++++++++++++++++++++++++ sections/people.md | 4 ++ 3 files changed, 110 insertions(+) create mode 100644 sections/out_of_office.md 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..3629e7f --- /dev/null +++ b/sections/out_of_office.md @@ -0,0 +1,105 @@ +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 +``` + +[1]: https://github.com/basecamp/bc3-api/blob/master/sections/people.md#get-person 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 From 96ec3310d7b264bee1e169871da400d5b4a53d25 Mon Sep 17 00:00:00 2001 From: Rob Zolkos Date: Thu, 12 Mar 2026 10:01:50 -0400 Subject: [PATCH 2/2] Remove unused reference link from out_of_office.md --- sections/out_of_office.md | 1 - 1 file changed, 1 deletion(-) diff --git a/sections/out_of_office.md b/sections/out_of_office.md index 3629e7f..36adcff 100644 --- a/sections/out_of_office.md +++ b/sections/out_of_office.md @@ -102,4 +102,3 @@ curl -s -H "Authorization: Bearer $ACCESS_TOKEN" -X DELETE \ https://3.basecampapi.com/$ACCOUNT_ID/people/2/out_of_office.json ``` -[1]: https://github.com/basecamp/bc3-api/blob/master/sections/people.md#get-person