<!-- https://developers.silktide.com/v1/platform/assignees/list-assignees | Platform / Assignees -->

# List the account's roles and users as assignees

`GET /v1/assignees`

Returns everyone and every role in the account that can be given something,
such as a report to receive or a check to fix, keyed by assignee id. Use these
ids wherever an operation asks for `assigneeIds`.

The answer is an object, not a list: read it by key, or take its values. Roles
come first, Everyone leading, then users, each in name order.

Roles and users have different fields. Both have `assigneeId`, `assigneeType`
and `displayName`; read the rest by `assigneeType`. Roles are still called
groups here (`group`, `groupId`, ids starting `g:`): that is the name roles
had before.

Older documentation listed eight assignee types. This list only ever holds
`group` and `user`.

## Response

Status `200`.

A map of objects. Every role, then every user, in the account, keyed by assignee id.

- `assigneeId` (string, required, matches `^[gu]:`): The assignee's id, the same as its key: `g:` and a role id, or `u:` and a user id.
- `assigneeType` (string, required): `group` for a role, `user` for a person. One of: `group`, `user`.
- `displayName` (string, required): The name to show: a role's name, or the name a person chose to be shown by.
- `groupId` (integer, optional, at least 1): The role's id, its `roleId`. Roles only.
- `name` (string, optional): The role's name again, as older integrations read it. Roles only.
- `description` (string, optional): What the role is for. Can be empty. Roles only.
- `icon` (string, optional): A Font Awesome icon class, such as `fas fa-globe`. Can be empty. Roles only.
- `colorScheme` (string, optional): The color Silktide shows the role in. Empty when it has none. Roles only. One of: `sky`, `emerald`, `amber`, `rose`, `orange`, `violet`, `indigo`, `cyan`, `fuchsia`, `slate`.
- `userId` (string, optional): The user's id: their region, a hyphen and a number, such as `eu-12`. Users only.
- `fullName` (string, optional): The person's full name. Users only.
- `email` (string, optional): Their email address. Users only.
- `position` (string, optional): Their job title. Empty when they have not given one. Users only.
- `thumbnailUrl` (string, optional): A URL of their picture. Empty when they have none. Users only.

## Errors

| Status | Type | When |
| --- | --- | --- |
| 401 | `NotLoggedIn` | No API key was sent, or it is not a key for this region. |
| 429 | `TooManyRequests` | Too many requests to this path in five seconds. Retry after the number of seconds in the `Retry-After` header, which `properties.retryAfter` repeats. |
| 503 | - | Silktide is busy. Retry after the number of seconds in the `Retry-After` header. |

## Access

- Permission: any user of the account
- Plan feature: none
- Edition: Silktide 4 and Silktide 5
- Cost: free
- Stability: stable, since 1.0.0

## Example: An account with two roles and two users

```bash
curl "https://api.eu.silktide.com/v1/assignees" \
  -H "Authorization: silktide token=$SILKTIDE_API_KEY"
```

Response:

```json
{
  "g:1": {
    "groupId": 1,
    "displayName": "Everyone",
    "description": "All users in this Account.",
    "icon": "fas fa-globe",
    "colorScheme": "sky",
    "assigneeId": "g:1",
    "assigneeType": "group",
    "name": "Everyone"
  },
  "g:2": {
    "groupId": 2,
    "displayName": "Account administrators",
    "description": "People with total control of this account",
    "icon": "fas fa-crown",
    "colorScheme": "amber",
    "assigneeId": "g:2",
    "assigneeType": "group",
    "name": "Account administrators"
  },
  "u:eu-12": {
    "userId": "eu-12",
    "fullName": "Jordan Rivera",
    "displayName": "Jordan",
    "email": "jordan.rivera@example.com",
    "position": "Web editor",
    "thumbnailUrl": "https://example.com/people/jordan.png",
    "assigneeId": "u:eu-12",
    "assigneeType": "user"
  },
  "u:eu-15": {
    "userId": "eu-15",
    "fullName": "Sam Okafor",
    "displayName": "Sam Okafor",
    "email": "sam.okafor@example.com",
    "position": "",
    "thumbnailUrl": "",
    "assigneeId": "u:eu-15",
    "assigneeType": "user"
  }
}
```