Case Fields

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:

  • String
  • Integer
  • Text
  • URL
  • Checkbox
  • Dropdown
  • User
  • Date
  • Milestone
  • Steps
  • Multiselect

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)

Was this article helpful?
2 out of 6 found this helpful