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
:user_id | 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 | int | The unique ID of the user |
is_active | bool | True if the user is active and false otherwise |
name | string | The full name of the user |
role_id | int | 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
200 | Success, the user is returned as part of the response |
400 | Invalid or unknown user |
get_current_user
Returns user details for the TestRail user making the API request.
GET index.php?/api/v2/get_current_user/:user_id
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 | int | The unique ID of the user |
is_active | bool | True if the user is active and false otherwise |
name | string | The full name of the user |
role_id | int | 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
200 | Success, the user is returned as part of the response |
400 | Invalid or unknown user |
get_user_by_email
Returns an existing user by his/her email address.
GET index.php?/api/v2/get_user_by_email&email=:email
The email address to get the user for |
This method uses the same response format as get_user.
info Note: Any user can retrieve his/her own account information. Retrieving information for any other user requires administrator access.
Response codes
200 | Success, the user is returned as part of the response |
400/404 | Invalid or unknown email address |
get_users
Returns a list of users.
GET index.php?/api/v2/get_users
:project_id | The ID of the project for which you would like to retrieve user information. (Required for non-administrators. Requires TestRail 6.4 or later.) |
Please Note:
- Non-administrators must include a project_id parameter.
- When a project_id is omitted, all user information is returned.
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
200 | Success, the users are returned as part of the response |
400 | Invalid project_id |
403 | Insufficient permissions |