Use the following API methods to request details about custom fields for test cases.
get_case_fields
Returns a list of available test case custom fields.
GET index.php?/api/v2/get_case_fields
Response content
The response includes an array of custom field definitions. Please see below for a typical response:
[
{
"configs": [
{
"context": {
"is_global": true,
"project_ids": null
},
"id": "..",
"options": {
"default_value": "",
"format": "markdown",
"is_required": false,
"rows": "5"
}
}
],
"description": "The preconditions of this test case. ..",
"display_order": 1,
"id": 1,
"label": "Preconditions",
"name": "preconds",
"system_name": "custom_preconds",
"type_id": 3
},
..
]
A custom field can have different configurations and options per project which is indicated by the configs
field. To check if a custom field is applicable to a specific project (and to find out the field options for this project), the context
of the field configuration must either be global (is_global
) or include the ID of the project in project_ids
.
Also, the following list shows the available custom field types (type_id
field):
Type ID | Name |
---|---|
1 | String |
2 | Integer |
3 | Text |
4 | URL |
5 | Checkbox |
6 | Dropdown |
7 | User |
8 | Date |
9 | Milestone |
10 | Steps |
12 | Multi-select |
Response codes
Status Code | Description |
---|---|
200 | Success (the available custom fields are returned as part of the response) |
429 |
TestRail Cloud only—Too many requests (see API rate limit) |
add_case_field
Creates a new test case custom field.
POST index.php?/api/v2/add_case_field
Request fields
The following POST fields are supported (system fields):
Name | Type | Required | Description |
---|---|---|---|
type | string | true |
The type identifier for the new custom field. The following types are supported:
You can pass the number of the type as well as the word, e.g. “5”, “string”, “String”, “Dropdown”, “12”. The numbers must be sent as a string e.g {type: “5”} not {type: 5}, otherwise, you will get a 400 (Bad Request) response. |
name | string | true | The name for new the custom field |
label | string | true | The label for the new custom field |
description | string | false | The description for the new custom field |
include_all | boolean | false | Set flag to true if you want the new custom field included for all templates. Otherwise (false) specify the ID’s of templates to be included as the next parameter (template_ids) |
template_ids | array | false | ID’s of templates new custom field will apply to if include_all is set to false |
configs | object | true | An object wrapped in an array with two default keys, ‘context’ and ‘options’ |
When creating new custom fields, use simple names without the “custom_” prefix since this will be added automatically. E.g. “my_int” will be prefixed with “custom_my_int”.
Custom fields with configs require the ‘context’ and ‘options’ default keys:
"configs": [
{
"context":{"is_global": true, "project_ids": []},
"options":{"is_required": false, "default_value": "1", "items": "1, First\n2, Second"}
}
]
To apply a custom field to specific projects, change the context:
"context": {"is_global": false, "project_ids": [5, 10]}
Some custom field types have different options. “is_required” (boolean) is common for all fields. Most of the types have the option to set “default_value” with exception for types Multiselect, Milestone and Date, where this option is not allowed..
Dropdown and Text have special options. For dropdown it is items:
"items": "1, First\n2, Second"
For text, use format and rows:
"format": "plain", "rows": "5"
For “format” choose between “plain” or “markdown” values. The “rows” option specifies the initial size of the field when the user loads a form. The valid values for it are e.g. “3”, “4”, …, “10” or “” (empty string).
"options": {
"is_required": false,
"default_value": "The default text.",
"format": "markdown",
"rows": "3"
}
Request example
{
"type": "Multiselect",
"name": "my_multiselect",
"label": "My Multiselect",
"description": "my custom Multiselect description",
"configs": [
{
"context": {
"is_global": true,
"project_ids": ""
},
"options": {
"is_required": false,
"items": "1, One\n2, Two"
}
}
],
"include_all": true
}
Response content
If successful, this method returns the new custom field.
{
"id":33,
"name":"my_multiselect",
"system_name":"custom_my_multiselect",
"entity_id":1,
"label":"My Multiselect",
"description":"my custom Multiselect description",
"type_id":12,
"location_id":2,
"display_order":7,
"configs":"[{\"context\":{\"is_global\":true,\"project_ids\":\"\"},\"options\":{\"is_required\":false,\"items\":\"1, One\\n2, Two\"},\"id\":\"9f105ba2-1ed0-45e0-b459-18d890bad86e\"}]",
"is_multi":1,
"is_active":1,
"status_id":1,
"is_system":0,
"include_all":1,
"template_ids": []
}
Response codes
Status Code | Description |
---|---|
200 | Success (the new custom field is returned in the response) |
400 | Bad request, check the error message for diagnostics |
404 | Not found, bad parameter passed |
429 |
TestRail Cloud only—Too many requests (see API rate limit) |