1. TestRail Support Center
  2. API Manual
  3. API reference

Users

Updated

Use the following API methods to request details about users.

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": 1,
    "email": "john.doe@gurock.io",
    "email_notifications": true,
    "is_active": true,
    "is_admin": false,
    "name": "John Doe",
    "role_id": 3,
    "role": "Tester",
    "group_ids": [1, 2, 3],
    "mfa_required": false
}

Response content (TestRail Enterprise)

{
    "id": 1,
    "email": "john.doe@gurock.io",
    "email_notifications": true,
    "is_active": true,
    "is_admin": false,
    "name": "John Doe",
    "role_id": 3,
    "role": "Tester",
    "group_ids": [1, 2, 3],
    "mfa_required": false,
    "sso_enabled": true,
    "assigned_projects": [1, 3]
}

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
email 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

 

Any user can retrieve his/her own account information. Retrieving information for any other use 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

{
    "id": 1,
    "email": "john.doe@gurock.io",
    "is_active": true,
    "name": "John Doe",
    "role_id": 3,
    "role": "Tester"
}

The following fields are included in the response:

Name Type Description
email 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

 

Any user can retrieve his/her own account information. Retrieving information for any other use 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
email string true The email address to get the user for

This method uses the same response format as get_user.

 

Any user can retrieve his/her own account information. Retrieving information for any other use 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}

 

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": "John Doe",
    },
    {
        "id": 2,
        "name": "Alexis Gonzalez",
    },
]

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

 

This endpoint requires TestRail 7.3 or later.

POST index.php?/api/v2/add_user

Request example

{
    "name": "John Doe",
    "email": "john.doe@gurock.io"
}

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.
email string The email address of the user. (Required)
email_notifications boolean False to disable email notifications for the user. Default: True.
is_active boolean True if the user is active or not. Default: False.
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

 

Was this article helpful?
5 out of 5 found this helpful