API: Users

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

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

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.

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}

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.

API: Users

On this page:

get_user

Parameters

Response content (TestRail Professional)

Response content (TestRail Enterprise)

Response codes

get_current_user

Parameters

Response content

Response codes

get_user_by_email

Parameters

Response codes

get_users

Parameters

Please Note:

When a project_id parameter is used:

Response content

Response codes

add_user

Request example

Response content

Response codes

update_user

Parameters

Request fields

Response content

Response codes