# Users

This resource lets you access users and their profiles in YouTrack.

|  Resource  |     ```GENERIC /api/users ```    |
| --- | --- |
|  Returned entity  |  [User](api-entity-User.html). For the description of the entity attributes, see [Supported Fields](#User-supported-fields) section.  |
|  Supported methods  |      * `GET`: [Read a List of Users](#get_all-User-method).    * `POST`: [Add a New User](#create-User-method).    |
|  Supported sub-resources  |      * [/api/users/{userID}](operations-api-users.html)    * [/api/users/{userID}/tags](resource-api-users-userID-tags.html)    * [/api/users/{userID}/savedQueries](resource-api-users-userID-savedQueries.html)    * [/api/users/{userID}/profiles/general](resource-api-users-userID-profiles-general.html)    * [/api/users/{userID}/profiles/notifications](resource-api-users-userID-profiles-notifications.html)    * [/api/users/{userID}/profiles/timetracking](resource-api-users-userID-profiles-timetracking.html)    |

## User attributes

Represents a user in YouTrack. Please note that the read-only properties of a user account, like credentials, or email and so on, you can only change in [Hub REST API](https://www.jetbrains.com.cn/en-us/help/youtrack/devportal/?Hub-REST-API).

### Related Resources

Below you can find the list of resources that let you work with this entity.

* [Users]()

* [Individual Users in the Bundle](resource-api-admin-customFieldSettings-bundles-user-bundleID-individuals.html)

* [Aggregated Users in the Bundle](resource-api-admin-customFieldSettings-bundles-user-bundleID-aggregatedUsers.html)

### Attributes

This table describes attributes of the `User` entity.

* To receive an attribute in the response from the server, specify it explicitly in the `fields` request parameter.

* To update an attribute, provide it in the body of a POST request.

|  Field  |  Type  |  Description  |
| --- | --- | --- |
|  id  |  String  |  The ID of the user. `Read-only`.  |
|  login  |  String  |  The login of the user. `Read-only`.  |
|  fullName  |  String  |  The full name of the user as seen in their profile. `Read-only`.  |
|  email  |  String  |  The email address of the user. `Read-only`. `Can be null`.  |
|  ringId  |  String  |  ID of the user in Hub. You can use this ID for operations in Hub, and for matching users between YouTrack and Hub. `Read-only`. `Can be null`.  |
|  guest  |  Boolean  |  Indicates whether the user is `guest`. `Read-only`.  |
|  online  |  Boolean  |  Indicates whether the user is currently online. `Read-only`.  |
|  banned  |  Boolean  |  Indicates whether the user is banned. `Read-only`.  |
|  banBadge  |  String  |  The badge displayed for the banned user. Returns `null` when no badge is set or the ban details are not available to the requester. `Read-only`. `Can be null`.  |
|  banReason  |  String  |  The reason why the user is banned. Returns `null` when no reason is set or the ban details are not available to the requester. `Read-only`. `Can be null`.  |
|  isAnonymized  |  Boolean  |  Indicates whether the user's personal data has been anonymized. `Read-only`.  |
|  tags  |  [Array of Tags](api-entity-Tag.html)  |  Tags that belong to this user. `Read-only`.  |
|  savedQueries  |  [Array of SavedQueries](api-entity-SavedQuery.html)  |  Saved searches that belong to this user. `Read-only`.  |
|  avatarUrl  |  String  |  The URL of the user avatar. `Read-only`.  |
|  profiles  |  [UserProfiles](api-entity-UserProfiles.html)  |  The profiles of the user. `Read-only`.  |
|  userType  |  [UserType](api-entity-UserType.html)  |  The type of the user.    Available since YouTrack 2026.2.    `Read-only`.  |

## Read a List of Users

Read the list of users in YouTrack.

### Request syntax

```GENERIC
GET /api/users?{fields}&{$top}&{$skip}
```

|  null  |  The database ID of User  |
| --- | --- |

### Request parameters

|  Parameter  |  Type  |  Description  |
| --- | --- | --- |
|  fields  |  String  |  A list of User attributes that should be returned in the response. If no field is specified, only the `entityID` is returned.  |
|  $skip  |  Int  |  Optional. Lets you set a number of returned entities to skip before returning the first one.  |
|  $top  |  Int  |     Optional. Lets you specify the maximum number of entries that are returned in the response. If you don't set the $top value, the server limits the maximum number of returned entries.       The server returns a maximum of 42 entries for most resources that return collections. For more information, see [Pagination](api-concept-pagination.html).     |

### Sample

#### Sample request

```CURL
https://example.youtrack.cloud/api/users?fields=id,login,fullName,email,name,online,banned&$top=5
```

#### Sample response body

```JSON
[
  {
    "email": null,
    "banned": true,
    "login": "guest",
    "online": false,
    "name": "guest",
    "fullName": "guest",
    "id": "24-1",
    "$type": "User"
  },
  {
    "email": "l.downton@example.com",
    "banned": false,
    "login": "Luisa_Downton",
    "online": false,
    "name": "Luisa Downton",
    "fullName": "Luisa Downton",
    "id": "24-55",
    "$type": "User"
  },
  {
    "email": "ariadne.naxos@example.com",
    "banned": false,
    "login": "ariadne.naxos",
    "online": false,
    "name": "Ariadne Naxos",
    "fullName": "Ariadne Naxos",
    "id": "24-50",
    "$type": "User"
  },
  {
    "email": "michael.scott@example.com",
    "banned": false,
    "login": "m.scott",
    "online": false,
    "name": "Michael Scott",
    "fullName": "Michael Scott",
    "id": "24-56",
    "$type": "User"
  },
  {
    "email": "minnie.terry@example.com",
    "banned": false,
    "login": "minnie.terry",
    "online": true,
    "name": "Minnie Terry",
    "fullName": "Minnie Terry",
    "id": "24-0",
    "$type": "User"
  }
]
```

## Add a New User

Create a user.

Required fields: `login`, `password`.

### Required permissions

Requires permission: Read User Basic, Create User.

### Request syntax

```GENERIC
POST /api/users?{fields}
```

|  null  |  The database ID of User  |
| --- | --- |

### Request parameters

|  Parameter  |  Type  |  Description  |
| --- | --- | --- |
|  fields  |  String  |  A list of User attributes that should be returned in the response. If no field is specified, only the `entityID` is returned.  |

### Sample

#### Sample request

```CURL
https://example.youtrack.cloud/api/users?fields=id,name,login,banned,email
```

#### Sample request body

```JSON
{
  "login": "Michael.Scott",
  "password": "password"
}
```

#### Sample response body

```JSON
{
  "email": null,
  "banned": false,
  "login": "Michael.Scott",
  "name": "Michael.Scott",
  "id": "24-62",
  "$type": "User"
}
```