> For the complete documentation index, see [llms.txt](https://docs.tiny.plus/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiny.plus/api/endpoints/team-members.md).

# Team Members

In the API, team members are `staff` records, so they live at `/v2/staff`. They support the requests on the [Records](/api/endpoints/records.md) page, with the rules below.

For a quick list of everyone's `id`, `name`, `role`, `email`, `record_url` and photo (`hero_path_uri`), use `GET /v2/staff_list`.

## Statuses

A team member's `record_status` is one of these:

| Status     | Means                                                             |
| ---------- | ----------------------------------------------------------------- |
| `active`   | They can sign in to tiny+, and use one of the account's licences. |
| `ghost`    | Records can be assigned to them, but they can't sign in.          |
| `disabled` | Shown in tiny+ as Deactivated. They can't sign in.                |

To list the active team members: `GET /v2/staff?record_status=active&return_format=array`.

## Adding a team member

Records admins can add team members. Account admins are records admins too. Send at least a `name` and an `email`:

```bash
curl -X POST "https://api.tiny.plus/v2/staff" \
  -H "Authorization: Bearer {{user_access_token}}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sam Sample", "email": "sam@example.com", "role": "Architect"}'
```

* A new team member is a `ghost` unless you send `"record_status": "active"`.
* An active team member gets a login, and an email inviting them to tiny+. They use one of the account's licences, and the account's seat count goes up if it needs to.
* `timezone` defaults to the account's.

If the team member can't be added, the response is `400` `{"error": "A pre-add processing error has occurred. - 22"}`, without the reason. The reason might be an email address that's already on the account, or no licence left for an active member.

## Changing a team member

People can change their own team member record, apart from their `email` and `record_status`. Account admins can change anyone's.

Some changes are ignored, although the response is still `{"results": true}`:

* changing your own `record_status`;
* making someone active when the account has no licence left;
* changing an active team member's `email`.

Setting someone to `ghost` or `disabled` stops them signing in. Deleting a team member removes their access to the account.

## Time zone

A team member's `timezone` is the zone tiny+ shows them times in, and counts their "today" in. People can change their own.

`GET /v2/fields/staff` lists the zones tiny+ offers as the field's `options`, as tiny+ shows them: ordered by UTC offset, then name. A label's offset is the zone's standard one, without daylight saving.

```json
"timezone": {
    "field_name": "timezone",
    "field_type": "timezone",
    "field_description": "Local Timezone",
    "options": [
        { "value": "Pacific/Pago_Pago", "label": "(UTC-11:00) American Samoa" },
        ...
        { "value": "Australia/Sydney", "label": "(UTC+10:00) Sydney, Canberra" },
        ...
        { "value": "Pacific/Auckland", "label": "(UTC+12:00) Auckland, Wellington" }
    ]
}
```

Send one of those `value`s, or any other zone name in the [IANA time zone database](https://www.iana.org/time-zones), such as `Europe/Oslo`. Names are case-sensitive. Anything else gets `400 {"error": "'timezone' must be a time zone name, such as Australia/Sydney."}`, and nothing is saved.

## Fields

| Field                | Label in tiny+           | Type          | Notes                                                                                                            | Editable            |
| -------------------- | ------------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------- |
| `birthday`           | Birthday                 | Date          | `YYYY-MM-DD`. Other people only see the day and month.                                                           | Yes                 |
| `default_home`       | Preferred Homepage       | Option        | One of the options listed by `GET /v2/fields/staff`.                                                             | Yes                 |
| `description`        | Bio                      | Text          |                                                                                                                  | Yes                 |
| `direct`             | Direct Line              | Phone number  |                                                                                                                  | Yes                 |
| `email`              | E-mail                   | Email address | Required. Their email address. Send it when you add a team member.                                               | Account admins only |
| `extension`          | Internal Extension       | Phone number  |                                                                                                                  | Yes                 |
| `generate_followups` | Enable Follow-ups        | Yes/no        | `1` to show them follow-up reminders about their records.                                                        | Yes                 |
| `last_visit_date`    | Last Login               | Date          | When they last used tiny+.                                                                                       | No                  |
| `linkedin`           | LinkedIn Profile         | URL           | Up to 1000 characters.                                                                                           | Yes                 |
| `mobile`             | Mobile                   | Phone number  |                                                                                                                  | Yes                 |
| `my_language`        | App Language             | Option        | One of the options listed by `GET /v2/fields/staff`.                                                             | Yes                 |
| `name`               | Full Name                | Text          | Required. Up to 200 characters.                                                                                  | Yes                 |
| `notification_prefs` | Notification Preferences | Option        | One of the options listed by `GET /v2/fields/staff`.                                                             | Yes                 |
| `qualifications`     | Qualifications           | Text          | Their post-nominals, such as `BArch`.                                                                            | Yes                 |
| `record_status`      | User Account Type        | Option        | `active`, `ghost` or `disabled`. See [Statuses](#statuses).                                                      | Account admins only |
| `role`               | Title                    | Text          | Their job title.                                                                                                 | Yes                 |
| `timezone`           | Local Timezone           | Time zone     | Their time zone, such as `Australia/Sydney`. The account's unless you send another. See [Time zone](#time-zone). | Yes                 |
| `twitter`            | Twitter Handle           | Text          |                                                                                                                  | Yes                 |