API: Users - TestRail

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

     

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

     

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