diff --git a/README.md b/README.md index 5bc1cbb..c6aedc6 100644 --- a/README.md +++ b/README.md @@ -282,6 +282,7 @@ API endpoints ------------- - [Authentication](https://github.com/basecamp/bc3-api/blob/master/sections/authentication.md#authentication) +- [Account](https://github.com/basecamp/bc3-api/blob/master/sections/account.md#account) - [Attachments](https://github.com/basecamp/bc3-api/blob/master/sections/attachments.md#attachments) - [Boosts](https://github.com/basecamp/bc3-api/blob/master/sections/boosts.md#boosts) - [Campfires](https://github.com/basecamp/bc3-api/blob/master/sections/campfires.md#campfires) diff --git a/sections/account.md b/sections/account.md new file mode 100644 index 0000000..76f107d --- /dev/null +++ b/sections/account.md @@ -0,0 +1,166 @@ +Account +======= + +Endpoints: + +- [Get account](#get-account) +- [Update account name](#update-account-name) +- [Update account logo](#update-account-logo) +- [Remove account logo](#remove-account-logo) + +Get account +----------- + +* `GET /account.json` will return the account for the current access token. + +The `logo` field is only present when the account has a logo configured. It is omitted entirely when no logo exists. + +###### Example JSON Response + +```json +{ + "id": 1009501286, + "name": "Honcho Design", + "owner_name": "Victor Cooper", + "active": true, + "created_at": "2026-03-16T21:42:20.134Z", + "updated_at": "2026-03-16T21:57:21.050Z", + "trial": false, + "trial_ends_on": null, + "frozen": false, + "paused": false, + "limits": { + "can_create_projects": true, + "can_pin_projects": true, + "can_create_users": true, + "can_upload_files": true + }, + "subscription": { + "short_name": "ClientsV1", + "proper_name": "Basecamp With Clients", + "project_limit": null, + "teams": true, + "clients": true, + "templates": true, + "logo": true, + "timesheet": true + }, + "settings": { + "company_hq_enabled": false, + "teams_enabled": true, + "projects_enabled": true + } +} +``` + + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" https://3.basecampapi.com/$ACCOUNT_ID/account.json +``` + +Update account name +------------------- + +* `PUT /account/name.json` will rename the current account. Only account owners can use this endpoint — returns `403 Forbidden` for non-owners. + +**Required parameters**: + +* `name` - the new name for the account. Returns `400 Bad Request` when blank. + +This endpoint returns `200 OK` with the full [account](#get-account) JSON representation on success. + +###### Example JSON Request + +```json +{ + "name": "Honcho Design Studio" +} +``` + +###### Example JSON Response + +```json +{ + "id": 1009501286, + "name": "Honcho Design Studio", + "owner_name": "Victor Cooper", + "active": true, + "created_at": "2026-03-16T21:42:20.134Z", + "updated_at": "2026-03-16T21:57:21.979Z", + "trial": false, + "trial_ends_on": null, + "frozen": false, + "paused": false, + "limits": { + "can_create_projects": true, + "can_pin_projects": true, + "can_create_users": true, + "can_upload_files": true + }, + "subscription": { + "short_name": "ClientsV1", + "proper_name": "Basecamp With Clients", + "project_limit": null, + "teams": true, + "clients": true, + "templates": true, + "logo": true, + "timesheet": true + }, + "settings": { + "company_hq_enabled": false, + "teams_enabled": true, + "projects_enabled": true + } +} +``` + + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ + -H "Content-Type: application/json" \ + -X PUT \ + -d '{"name":"Honcho Design Studio"}' \ + https://3.basecampapi.com/$ACCOUNT_ID/account/name.json +``` + +Update account logo +------------------- + +* `PUT /account/logo.json` will upload or replace the account logo. Only administrators and account owners can use this endpoint — returns `403 Forbidden` for others. + +Account logos use direct multipart file upload rather than the standard two-stage `/attachments` flow used elsewhere in the API. + +**Required parameters**: + +* `logo` - the logo image file, sent as a multipart form upload. Accepted formats: PNG, JPEG, GIF, WebP, AVIF, HEIC. Maximum file size: 5 MB. Returns `422 Unprocessable Entity` when the file is missing, the format is invalid, or the file exceeds 5 MB. + +Returns `204 No Content` on success. + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ + -X PUT \ + -F "logo=@company-logo.png" \ + https://3.basecampapi.com/$ACCOUNT_ID/account/logo.json +``` + +Remove account logo +------------------- + +* `DELETE /account/logo.json` will remove the account logo. Only administrators and account owners can use this endpoint — returns `403 Forbidden` for others. + +Returns `204 No Content` on success. + +###### Copy as cURL + +```shell +curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \ + -X DELETE \ + https://3.basecampapi.com/$ACCOUNT_ID/account/logo.json +```