API: Users
Use the following API methods to request details about users.
On this page:
get_user
Returns an existing user.
GET index.php?/api/v2/get_user/{user_id}
Parameters
Name | Type | Required | Description |
user_id |
integer | true | The ID of the user |
Response content (TestRail Professional)
{
"id": integer,
"email": string,
"email_notifications": boolean,
"is_active": boolean,
"is_admin": boolean,
"name": string,
"role_id": integer,
"role": string,
"group_ids": [integer_list],
"mfa_required": boolean
}
Response content (TestRail Enterprise)
{
"id": integer,
"email": string,
"email_notifications": boolean,
"is_active": boolean,
"is_admin": boolean,
"name": string,
"role_id": integer,
"role": string,
"group_ids": [integer_list],
"mfa_required": boolean,
"assigned_projects": [integer list],
"sso_enabled": boolean
}
The following fields are included in the response
Name | Type | Description |
assigned_projects
|
array | An array of project IDs. Each ID is a project to which the user is assigned. See Project Level Administration for more information. (Requires TestRail Enterprise 7.3 or later) |
|
string | The email address of the user as configured in TestRail |
email_notifications
|
boolean | True if email notifications are enabled for the user. (Requires TestRail 7.3 or later) |
id |
integer | The unique ID of the user |
is_active |
boolean | True if the user is active and false otherwise |
is_admin
|
boolean | True if the user is a TestRail administrator. (Requires TestRail 7.3 or later) |
group_ids
|
array | An array of group IDs. Each ID is a group to which the user is assigned. (Requires TestRail 7.3 or later) |
mfa_required
|
boolean | True if the user profile is configured to require MFA at each login. (Requires TestRail 7.3 or later) |
name |
string | The full name of the user |
role_id |
integer | The unique ID of the user’s globally assigned role – requires TestRail 6.4 or later |
role |
string | The Name of the user’s globally assigned role – requires TestRail 6.4 or later |
sso_enabled
|
boolean | True if the user’s profile has Single-Sign-On enabled. (Requires TestRail Enterprise 7.3 or later) |
info Note: Any user can retrieve his/her own account information. Retrieving information for any other user requires administrator access.
Response codes
Status Code | Description |
200 |
Success (the user is returned as part of the response) |
400 |
Invalid or unknown user |
429 |
TestRail Cloud only—Too many requests (see API rate limit) |
get_current_user
This endpoint requires TestRail 6.6 or later.
Returns user details for the TestRail user making the API request.
GET index.php?/api/v2/get_current_user/{user_id}
Parameters
Name | Type | Required | Description |
user_id |
integer | true | The ID of the user |
Response content
{
"email": "[email protected]",
"id": 1,
"is_active": true,
"name": "Alexis Gonzalez",
"role_id": "1",
"role": "Lead"
}
The following fields are included in the response
Name | Type | Description |
|
string | The email address of the user as configured in TestRail |
id |
integer | The unique ID of the user |
is_active |
boolean | True if the user is active and false otherwise |
name |
string | The full name of the user |
role_id |
integer | The unique ID of the user’s globally assigned role – requires TestRail 6.4 or later |
role |
string | The Name of the user’s globally assigned role – requires TestRail 6.4 or later |
info Note: Any user can retrieve his/her own account information. Retrieving information for any other user requires administrator access.
Response codes
Status Code | Description |
200 |
Success (the user is returned as part of the response) |
400 |
Invalid or unknown user |
429 |
TestRail Cloud only—Too many requests (see API rate limit) |
get_user_by_email
Returns an existing user by his/her email address.
GET index.php?/api/v2/get_user_by_email&email={email}
Parameters
Name | Type | Required | Description |
|
string | true | The email address to get the user for |
This method uses the same response format as get_user.
info Note: Any user can retrieve their own account information. Retrieving information for any other user requires administrator access.
Response codes
Status Code | Description |
200 |
Success (the user is returned as part of the response) |
400/404 |
Invalid or unknown email address |
429 |
TestRail Cloud only—Too many requests (see API rate limit) |
get_users
Returns a list of users.
GET index.php?/api/v2/get_users GET index.php?/api/v2/get_users/{project_id}
info Note: As of TestRail 6.6, only administrators can use get_users without a project_id parameter. Non-administrators are required to use the project_id parameter.
Parameters
Name | Type | Required | Description |
project_id |
integer | true | The ID of the project for which you would like to retrieve user information. (Required for non-administrators.) – requires TestRail 6.6 or later |
Please Note:
- Non-administrators must include a project_id parameter.
- When a project_id is omitted, all user information is returned.
- get_users/{project_id} only retrieves users with explicit project access and does not list users with global access.
When a project_id parameter is used:
- The role and role_id values returned will correspond to the user’s project-level access.
- Inactive users are not included in the response.
- Users without access to the project are not included in the response.
Response content
[
{ "id": 1, "name": "Alexis Gonzalez", .. },
{ "id": 2, "name": "Ciaran Davenport", .. },
..
]
The response includes an array of users. Each user in this list follows the same format as get_user.
Response codes
Status Code | Description |
200 |
Success (the users are returned as part of the response) |
400 |
Invalid project_id |
403 |
Insufficient permissions |
429 |
TestRail Cloud only—Too many requests (see API rate limit) |
add_user
Creates a new user.
(Requires TestRail 7.3 or later)
POST index.php?/api/v2/add_user
Request example
{
"name": “John Doe”,
“email”: “[email protected]”
}
The following fields are included in the response
Name | Type | Description |
assigned_projects
|
array | An array of project IDs to assign to a Project Level Administrator. See Project Level Administration for more information. |
|
string | The email address of the user. (Required) |
email_notifications
|
boolean | False to disable email notifications for the user. Default: True. |
is_admin |
boolean | True to make the user a TestRail Administrator. Default: False. |
group_ids
|
array | Array of group IDs to assign the user to |
mfa_required |
boolean | True to require Multi-Factor Authentication for the user. Default value matches the MFA setting of the instance. |
name |
string | The name of the user. (Required) |
role_id
|
integer | The ID of the global role to assign to the user. |
sso_enabled
|
boolean | True to enable SSO for the user. Default value matches the SSO setting of the instance. |
Response content
If successful, this method returns the new user using the same response format as get_user.
Response codes
Status Code | Description |
200 |
Success, the user was created. |
400 |
Invalid field value, such as an email address. |
403 |
No permission to create users. |
update_user
Updates an existing user.
POST index.php?/api/v2/update_user/:user_id
Parameters
Name | Type | Required | Description |
user_id
|
integer | true | The ID of the user |
Request fields
This endpoint supports the same fields as add_user.
Response content
If successful, this method returns the updated user using the same response format as get_user.
Response codes
Status Code | Description |
200 |
Success, the user was updated. |
400 |
Invalid field value, such as an email address. |
403 |
No permission to update users. |