# People API

This group covers the workspace's people: the team directory, member profiles, the people lookup and expertise tags, and the caller's own profile, status, Do Not Disturb, language and time zone. Every call acts as a person: send a personal access token, or an OAuth access token from a person's sign-in (scope `Volobox`). An integration app's own client secret is refused with `403` (`Volobox:Integrations:MemberConnectionRequired`). Paths, tokens and conventions are in [API overview](/docs/api-overview).

## Members and profiles

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| PUT | `/api/v1/app-user/{id}/profile` | `people.appUser.updateTeamMemberProfile` | Corrects the structured profile fields of a workspace member, for people managers. |
| GET | `/api/v1/app-user/{id}/team-member-profile` | `people.appUser.getTeamMemberProfile` | Gets a workspace member's profile by id. |
| GET | `/api/v1/app-user/by-username/{userName}/team-member-profile` | `people.appUser.getTeamMemberProfileByUserName` | Gets a workspace member's profile by user name. |
| PUT | `/api/v1/app-user/my-dnd` | `people.appUser.setMyDoNotDisturb` | Turns the caller's Do Not Disturb on until a given time, or off. Acts on the signed-in person's own account. |
| PUT | `/api/v1/app-user/my-dnd/outside-working-hours` | `people.appUser.setMyDoNotDisturbOutsideWorkingHours` | Turns the caller's Do Not Disturb on or off automatically outside their working hours. Acts on the signed-in person's own account. |
| GET | `/api/v1/app-user/my-profile` | `people.appUser.getMyProfile` | Gets the caller's own profile. Acts on the signed-in person's own account. |
| PUT | `/api/v1/app-user/my-profile` | `people.appUser.updateMyProfile` | Changes the caller's own profile. Acts on the signed-in person's own account. |
| PUT | `/api/v1/app-user/my-status` | `people.appUser.setMyStatus` | Sets the caller's own status, until a given time or until cleared, with an optional note. Acts on the signed-in person's own account. |
| DELETE | `/api/v1/app-user/my-status` | `people.appUser.clearMyStatus` | Clears the caller's own status. Acts on the signed-in person's own account. |
| GET | `/api/v1/app-user/team-directory` | `people.appUser.getTeamDirectory` | Lists the workspace's active members with their presence, vacation and working-hours state. |

Request bodies:

- `UpdateTeamMemberProfileDto` (`updateTeamMemberProfile`): no field is required.
- `UpdateMyProfileDto` (`updateMyProfile`): no field is required.

## Expertise tags

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/expertise-tags` | `people.expertiseTags.getAdminList` | Lists every expertise term with how many people claim it, for people managers. |
| PUT | `/api/v1/expertise-tags/{id}` | `people.expertiseTags.rename` | Renames an expertise term, for people managers. |
| DELETE | `/api/v1/expertise-tags/{id}` | `people.expertiseTags.delete` | Deletes an expertise term and every claim of it, for people managers. |
| POST | `/api/v1/expertise-tags/merge` | `people.expertiseTags.merge` | Folds expertise terms into another one and deletes them, for people managers. |
| GET | `/api/v1/expertise-tags/search` | `people.expertiseTags.search` | Searches the expertise terms people have claimed, by name. |

## People lookup

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/people/lookup/{id}` | `people.lookup.get` | Looks up one active workspace member by id. |
| GET | `/api/v1/people/lookup/by-username/{userName}` | `people.lookup.getByUserName` | Looks up one active workspace member by user name. |
| GET | `/api/v1/people/lookup/search` | `people.lookup.search` | Searches the active workspace members by user name, name, surname or email, at most 50 at a time. |

## Language and time zone

| Method | Path | Operation | Summary |
| --- | --- | --- | --- |
| GET | `/api/v1/me/language` | `people.me.getLanguage` | Gets the caller's language. Acts on the signed-in person's own account. |
| PUT | `/api/v1/me/language` | `people.me.updateLanguage` | Changes the caller's language. Acts on the signed-in person's own account. |
| PUT | `/api/v1/me/time-zone` | `people.me.updateTimeZone` | Changes the caller's time zone. Acts on the signed-in person's own account. |

Request bodies:

- `UpdateLanguageDto` (`updateLanguage`): no field is required.
- `UpdateTimeZoneDto` (`updateTimeZone`): requires `source` (string), `timeZoneId` (string).

## Example

`people.appUser.getMyProfile`: gets the caller's own profile.

```bash title="curl"
curl -s "https://volobox.example.com/api/v1/app-user/my-profile" \
  -H "Authorization: Bearer $VOLOBOX_TOKEN"
```
